@meetless/mla 0.1.4

package/dist/lib/analytics/sequence.js

@@ -0,0 +1,77 @@
+"use strict";
+// Per-session command sequence fields (spec section 6.2: command_index_in_session,
+// preceded_by, session_idle_gap_ms). These unlock PostHog path analysis (section
+// 8: the `preceded_by` Sankey) without any second on-disk tracker: the local
+// events.jsonl is already the single source of truth for `mla stats`, so the
+// prior commands of a session are simply the `mla_command` rows that already
+// carry the same session_id. Deriving from the jsonl keeps one source of truth
+// and cannot drift from what `mla stats` sees.
+//
+// Computed BEFORE the current event is appended, so the rows read here are the
+// strictly-prior commands of this session.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeSequence = computeSequence;
+const store_1 = require("./store");
+// Sequence fields are null for an unbound run (no session to order within).
+const NO_SEQUENCE = {
+    command_index_in_session: null,
+    preceded_by: null,
+    session_idle_gap_ms: null,
+};
+function eventMillis(ev) {
+    const raw = ev.emitted_at || ev.created_at;
+    if (!raw)
+        return null;
+    const ms = Date.parse(raw);
+    return Number.isNaN(ms) ? null : ms;
+}
+// Derive the sequence fields for the command about to be recorded. `readEvents`
+// is the injectable read so a test can drive it off a tmp MEETLESS_HOME; when
+// local stats are off it returns [], which correctly yields index 1 / no
+// predecessor (we have no local working set to order against).
+function computeSequence(sessionId, commandStartedAtMs, env = process.env) {
+    if (!sessionId)
+        return NO_SEQUENCE;
+    const prior = [];
+    for (const ev of (0, store_1.readEvents)(env)) {
+        if (ev.event_type === "mla_command" && ev.session_id === sessionId) {
+            prior.push(ev);
+        }
+    }
+    // 1-based position of this command in the session.
+    const index = prior.length + 1;
+    if (prior.length === 0) {
+        // First command of the session: no predecessor, no idle gap to measure.
+        return {
+            command_index_in_session: index,
+            preceded_by: null,
+            session_idle_gap_ms: null,
+        };
+    }
+    // The immediately-preceding command is the latest prior row by ship time.
+    let latest = prior[0];
+    let latestMs = eventMillis(prior[0]);
+    for (const ev of prior) {
+        const ms = eventMillis(ev);
+        if (ms !== null && (latestMs === null || ms >= latestMs)) {
+            latest = ev;
+            latestMs = ms;
+        }
+    }
+    const precededBy = typeof latest.command === "string"
+        ? latest.command
+        : null;
+    // Idle gap = this command's start minus the prior command's recorded time.
+    // Clamp a negative result (clock skew, out-of-order rows) to null rather than
+    // emit a nonsense negative duration.
+    let idleGap = null;
+    if (latestMs !== null) {
+        const gap = commandStartedAtMs - latestMs;
+        idleGap = gap >= 0 ? gap : null;
+    }
+    return {
+        command_index_in_session: index,
+        preceded_by: precededBy,
+        session_idle_gap_ms: idleGap,
+    };
+}

package/dist/lib/analytics/store.js

@@ -0,0 +1,131 @@
+"use strict";
+// Local analytics store: the append-only ~/.meetless/events.jsonl (spec section
+// 7.4, INV-LOCAL-STATS-1/2). This file is the source of truth for `mla stats`
+// (offline, OSS-safe, no backend required) and the local correlator's working
+// set. It is NEVER the source of truth for `--global` (that reads control
+// rollups).
+//
+// Every write is gated by localStatsEnabled() so a user who turns local stats
+// off leaves no trace on disk. Reads are lenient: a malformed line is skipped,
+// never fatal, so a half-written line (crash mid-append) can't brick `mla stats`.
+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.eventsPath = eventsPath;
+exports.machineId = machineId;
+exports.appendEvent = appendEvent;
+exports.appendEventLine = appendEventLine;
+exports.readEvents = readEvents;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const config_1 = require("../config");
+const consent_1 = require("./consent");
+function eventsPath() {
+    return path.join(config_1.HOME, "events.jsonl");
+}
+// A stable, non-identifying machine id for distinct_id when no workspace user is
+// resolved. Derived from the hostname + home dir so it is consistent per machine
+// but carries no account data. Hashed so the raw hostname never lands in jsonl.
+let cachedMachineId = null;
+function machineId() {
+    if (cachedMachineId)
+        return cachedMachineId;
+    const seed = `${os.hostname()}::${os.homedir()}`;
+    cachedMachineId = "m_" + crypto.createHash("sha256").update(seed).digest("hex").slice(0, 24);
+    return cachedMachineId;
+}
+function ensureHome() {
+    if (!fs.existsSync(config_1.HOME)) {
+        fs.mkdirSync(config_1.HOME, { recursive: true });
+    }
+}
+// Append one event as a single jsonl line. No-op when local stats are disabled.
+// Best-effort: a disk error is swallowed (analytics must never break a command),
+// but we surface it on the debug channel via the optional onError hook.
+function appendEvent(ev, env = process.env, onError) {
+    if (!(0, consent_1.localStatsEnabled)(env))
+        return;
+    try {
+        ensureHome();
+        fs.appendFileSync(eventsPath(), JSON.stringify(ev) + "\n", "utf8");
+    }
+    catch (err) {
+        if (onError)
+            onError(err);
+    }
+}
+// Append a raw pre-serialized line (used by the correlator when it rewrites an
+// outcome). Same gating + best-effort semantics.
+function appendEventLine(line, env = process.env, onError) {
+    if (!(0, consent_1.localStatsEnabled)(env))
+        return;
+    try {
+        ensureHome();
+        const normalized = line.endsWith("\n") ? line : line + "\n";
+        fs.appendFileSync(eventsPath(), normalized, "utf8");
+    }
+    catch (err) {
+        if (onError)
+            onError(err);
+    }
+}
+// Read all events from the local jsonl. Lenient parser: blank and malformed
+// lines are skipped. Returns [] when the file is absent or local stats are off.
+function readEvents(env = process.env) {
+    if (!(0, consent_1.localStatsEnabled)(env))
+        return [];
+    const file = eventsPath();
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            out.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip a half-written or corrupt line; never fail the read.
+        }
+    }
+    return out;
+}

package/dist/lib/analytics/turn-recap.js

@@ -0,0 +1,279 @@
+"use strict";
+// Per-turn assist recap (Layer A of notes/20260609-mla-per-turn-assist-recap-plan.md).
+//
+// The session-level `mla stats` / `mla adoption` reader answers "across this
+// session, how often was injected evidence used?" This module is the per-TURN
+// analog: for one (session_id, turn_index) it answers the two operator questions
+// An asked for at the end of every turn:
+//
+//   liveness   -- did mla run this turn, or silently not fire? (ran / not_run_reason)
+//   usefulness -- if it offered evidence, was the evidence pulled or cited, or
+//                 ignored? (verdict USED / IGNORED / NO_OFFER / NOT_RUN)
+//
+// It reuses the SAME three local spool files and the SAME overlap math as the
+// followthrough reader (INV-ADOPTION-SOURCE-1) so a per-turn USED is exactly the
+// per-turn instance of the session-level A1c. The only new parse is a single-turn
+// ask-traces reader; mcp-calls and report-citations go through followthrough's
+// parsers unchanged. Window is 0 (same turn): this is computed at Stop, when all
+// of the turn's pulls (written during the turn) and citations (written by stop.sh
+// moments earlier) are already on disk, so the cross-turn window the session
+// reader needs does not apply here.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAskTrace = parseAskTrace;
+exports.computeTurnRecap = computeTurnRecap;
+exports.renderFooter = renderFooter;
+exports.renderBlockContext = renderBlockContext;
+exports.renderBlock = renderBlock;
+const logs_1 = require("./logs");
+const followthrough_1 = require("./followthrough");
+function asObj(v) {
+    return v && typeof v === "object" ? v : {};
+}
+function asStr(v) {
+    return typeof v === "string" ? v : "";
+}
+function asNum(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+const NOT_RUN_REASONS = ["muted", "not_activated", "suppressed", "timeout", "error"];
+function asNotRunReason(v) {
+    return typeof v === "string" && NOT_RUN_REASONS.includes(v) ? v : null;
+}
+// parseAskTrace reads ONE ask-traces.jsonl line into the fields the recap needs.
+// Returns null when the line cannot join (no session_id or non-numeric turn).
+// The offered set mirrors parseInjectTurns: enrichment.context_items[] with
+// injected===true and a non-empty source_id (the ids mla actually PUSHED).
+function parseAskTrace(line) {
+    const session_id = asStr(line.session_id);
+    const turn_index = asNum(line.turn_index);
+    if (!session_id || turn_index === null)
+        return null;
+    const hook = asObj(line.hook);
+    const arbitration = asObj(line.arbitration);
+    const enrichment = asObj(line.enrichment);
+    const items = Array.isArray(enrichment.context_items) ? enrichment.context_items : [];
+    const offered = [];
+    for (const raw of items) {
+        const item = asObj(raw);
+        if (item.injected !== true)
+            continue;
+        const sid = asStr(item.source_id);
+        if (sid)
+            offered.push(sid);
+    }
+    const failOpen = asStr(hook.fail_open_reason);
+    // The early-exit minimal line (Phase 1 §5 enabling change) names its reason
+    // explicitly; accept it from hook or top-level so the writer has either home.
+    const explicitReason = asNotRunReason(hook.not_run_reason) ?? asNotRunReason(line.not_run_reason);
+    return {
+        session_id,
+        turn_index,
+        trace_id: typeof line.trace_id === "string" && line.trace_id ? line.trace_id : null,
+        injected_floor: hook.injected === true,
+        injected_evidence: hook.layer2_injected === true,
+        enrich_latency_ms: asNum(hook.enrich_latency_ms),
+        offered_source_ids: Array.from(new Set(offered)),
+        arb_reason: asStr(arbitration.reason),
+        fail_open_reason: failOpen || null,
+        not_run_reason: explicitReason,
+        has_error: line.error != null,
+    };
+}
+// Why mla did not RUN (or suppressed injection) this turn. Only meaningful when
+// the floor was not injected (a control, suppression, or early-exit). An explicit
+// minimal-line reason wins; otherwise the injected=false control maps to
+// "suppressed". An injected floor means it ran, so this is null there.
+function deriveNotRunReason(t) {
+    if (!t)
+        return null; // no line at all: reason unknown
+    if (t.not_run_reason)
+        return t.not_run_reason;
+    const arb = t.arb_reason.toLowerCase();
+    if (arb.includes("pull_only") || arb.includes("suppress"))
+        return "suppressed";
+    if (t.fail_open_reason === "timeout")
+        return "timeout";
+    if (t.fail_open_reason === "error" || t.has_error)
+        return "error";
+    return null;
+}
+// Why nothing was OFFERED this turn though mla ran (floor injected, no evidence).
+// Feeds the NO_OFFER footer and the session-level "coverage gaps" vocabulary.
+function deriveCoverageGap(t) {
+    const arb = t.arb_reason.toLowerCase();
+    const fail = (t.fail_open_reason ?? "").toLowerCase();
+    if (arb.includes("no_relevant_context"))
+        return "no_relevant_context";
+    // Auth rejection (expired/revoked CLI token) is checked before the generic
+    // error so a dead session reads as "re-auth", not "enrichment failed".
+    if (fail === "unauthorized" || arb.includes("unauthorized"))
+        return "enrich_unauthorized";
+    if (fail === "timeout" || arb.includes("timeout"))
+        return "enrich_timeout";
+    if (fail === "error" || arb.includes("error"))
+        return "enrich_error";
+    if (arb.includes("missing_token"))
+        return "missing_token";
+    return null;
+}
+// --- the join ----------------------------------------------------------------
+function computeTurnRecap(sessionId, turnIndex, deps = {}) {
+    const readLog = deps.readLog ?? logs_1.readLogJsonl;
+    const askLines = readLog("ask-traces.jsonl");
+    const mcpLines = (0, followthrough_1.parseMcpCalls)(readLog("mcp-calls.jsonl"));
+    const citeLines = (0, followthrough_1.parseReportCitations)(readLog("report-citations.jsonl"));
+    // The single ask-traces line for this turn. One line per turn is the invariant
+    // (write_trace is the sole emitter); take the last match so a re-emit wins.
+    let trace = null;
+    for (const raw of askLines) {
+        const t = parseAskTrace(raw);
+        if (t && t.session_id === sessionId && t.turn_index === turnIndex)
+            trace = t;
+    }
+    const ran = trace !== null;
+    const injected_floor = trace?.injected_floor ?? false;
+    const injected_evidence = trace?.injected_evidence ?? false;
+    const offered_source_ids = trace?.offered_source_ids ?? [];
+    const evidence_offered = offered_source_ids.length > 0;
+    // Same-turn, same-session pulls and citations (window=0).
+    const pulledIds = [];
+    const toolSet = new Set();
+    let pull_count = 0;
+    for (const c of mcpLines) {
+        if (c.session_id !== sessionId || c.turn_index !== turnIndex || !c.evidence_tool)
+            continue;
+        pull_count += 1;
+        pulledIds.push(...c.source_ids);
+        if (c.tool)
+            toolSet.add(c.tool);
+    }
+    const cited_source_ids = [];
+    for (const r of citeLines) {
+        if (r.session_id !== sessionId || r.turn_index !== turnIndex)
+            continue;
+        cited_source_ids.push(...r.source_ids);
+    }
+    // Referenced = offered ids the agent pulled (via an evidence tool) or cited.
+    const referenced_source_ids = (0, followthrough_1.overlap)(offered_source_ids, [...pulledIds, ...cited_source_ids]);
+    const notRun = !ran || !injected_floor;
+    const not_run_reason = notRun ? deriveNotRunReason(trace) : null;
+    const coverage_gap_type = !notRun && !evidence_offered ? deriveCoverageGap(trace) : null;
+    let verdict;
+    if (notRun)
+        verdict = "NOT_RUN";
+    else if (!evidence_offered)
+        verdict = "NO_OFFER";
+    else if (referenced_source_ids.length === 0)
+        verdict = "IGNORED";
+    else
+        verdict = "USED";
+    return {
+        session_id: sessionId,
+        turn_index: turnIndex,
+        trace_id: trace?.trace_id ?? null,
+        ran,
+        injected_floor,
+        injected_evidence,
+        not_run_reason,
+        enrich_latency_ms: trace?.enrich_latency_ms ?? null,
+        evidence_offered,
+        offered_source_ids,
+        zero_results: !evidence_offered,
+        coverage_gap_type,
+        evidence_tools_pulled: Array.from(toolSet),
+        pull_count,
+        referenced_source_ids,
+        cited_source_ids,
+        verdict,
+    };
+}
+// --- render ------------------------------------------------------------------
+function gapPhrase(t) {
+    switch (t) {
+        case "no_relevant_context":
+            return "no candidate matched your prompt";
+        case "enrich_timeout":
+            return "enrichment timed out";
+        case "enrich_unauthorized":
+            return "Meetless session expired, run `mla login`";
+        case "enrich_error":
+            return "enrichment failed";
+        case "missing_token":
+            return "no auth token";
+        default:
+            return "nothing relevant offered";
+    }
+}
+function notRunPhrase(r) {
+    switch (r) {
+        case "muted":
+            return "muted this session";
+        case "not_activated":
+            return "not activated for this repo";
+        case "suppressed":
+            return "injection suppressed";
+        case "timeout":
+            return "hook timed out";
+        case "error":
+            return "hook error";
+        default:
+            return "did not run (reason unknown)";
+    }
+}
+function pulledPhrase(r) {
+    if (r.pull_count === 0)
+        return "0";
+    const names = r.evidence_tools_pulled.length ? r.evidence_tools_pulled.join("+") : "evidence";
+    return `${names} ×${r.pull_count}`;
+}
+function citedPhrase(r) {
+    return r.cited_source_ids.length ? r.cited_source_ids.join(", ") : "0";
+}
+// The single-line, scannable footer (Section 7). Also used as the Langfuse score
+// comment (Layer D) and the `mla turn` headline, so all three surfaces agree.
+function renderFooter(r) {
+    const head = `🔎 mla · turn ${r.turn_index}`;
+    if (r.verdict === "NOT_RUN")
+        return `${head} · ${notRunPhrase(r.not_run_reason)} · NOT_RUN`;
+    if (r.verdict === "NO_OFFER")
+        return `${head} · floor only · ${gapPhrase(r.coverage_gap_type)} · NO_OFFER`;
+    const latency = r.enrich_latency_ms != null ? `${r.enrich_latency_ms}ms` : "?ms";
+    const offer = `evidence injected (${r.offered_source_ids.length} src, ${latency})`;
+    return `${head} · ${offer} · pulled ${pulledPhrase(r)} · cited ${citedPhrase(r)} · ${r.verdict}`;
+}
+// The C-lite injection payload: the footer wrapped in a context block with one
+// soft, optional nudge. Best-effort surfacing; never a command (D3).
+function renderBlockContext(r) {
+    return [
+        `<meetless-context kind="turn-recap" for-turn="${r.turn_index}">`,
+        renderFooter(r),
+        "You may surface this assist recap to the operator as a one-line footer if useful.",
+        "</meetless-context>",
+    ].join("\n");
+}
+// The full multi-line expansion for `mla turn` human output.
+function renderBlock(r) {
+    const ranDesc = !r.ran
+        ? "no (no trace for this turn)"
+        : !r.injected_floor
+            ? `suppressed (${r.not_run_reason ?? "control"})`
+            : r.injected_evidence
+                ? "floor + evidence"
+                : "floor only";
+    const offeredDesc = r.evidence_offered
+        ? `${r.offered_source_ids.length} source(s): ${r.offered_source_ids.join(", ")}`
+        : `none${r.coverage_gap_type ? ` (${r.coverage_gap_type})` : ""}`;
+    const lines = [
+        `🔎 mla turn ${r.turn_index} recap`,
+        `  ran:        ${ranDesc}`,
+        `  offered:    ${offeredDesc}`,
+        `  latency:    ${r.enrich_latency_ms != null ? `${r.enrich_latency_ms}ms` : "n/a"}`,
+        `  pulled:     ${pulledPhrase(r)}`,
+        `  cited:      ${citedPhrase(r)}`,
+        `  referenced: ${r.referenced_source_ids.length ? r.referenced_source_ids.join(", ") : "none"}`,
+        `  verdict:    ${r.verdict}`,
+    ];
+    if (r.trace_id)
+        lines.push(`  trace:      ${r.trace_id}`);
+    return lines.join("\n");
+}

package/dist/lib/artifact_id.js

@@ -0,0 +1,108 @@
+"use strict";
+// Artifact ID resolver for `mla kb` commands.
+// Source: notes/20260530-mla-kb-curation-cli-proposal-v2.md §3.5 + §4.2.
+//
+// Inputs accepted on the command line:
+//   kbdoc:<id>           the canonical id of a KbDocument row.
+//   kbdocrev:<id>        the id of a specific KbDocumentRevision row.
+//   note:<canonicalPath> legacy form during the deprecation window (§3.4).
+//   <bare path>          treated as a canonical path the server will resolve.
+//
+// Client-side this layer does NOT canonicalize paths. Canonicalization lives
+// server-side in intel's canonicalize_note_path() so that the case-fold rule
+// and unicode NFC step apply consistently across CLI, MCP, and worker
+// callers. The helper exists to (a) classify the operator's input shape, and
+// (b) build display strings for receipts.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArtifactInputError = void 0;
+exports.parseArtifactInput = parseArtifactInput;
+exports.formatKbDocId = formatKbDocId;
+exports.formatKbDocRevId = formatKbDocRevId;
+exports.formatArtifactInput = formatArtifactInput;
+exports.toResolverQuery = toResolverQuery;
+class ArtifactInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ArtifactInputError";
+    }
+}
+exports.ArtifactInputError = ArtifactInputError;
+const KBDOC_PREFIX = "kbdoc:";
+const KBDOCREV_PREFIX = "kbdocrev:";
+const NOTE_PREFIX = "note:";
+// Parse a positional input from `mla kb show / forget / reingest / purge /
+// move`. Empty strings are rejected because they would silently degrade to a
+// bare-path branch that resolves nothing.
+function parseArtifactInput(raw) {
+    if (typeof raw !== "string") {
+        throw new ArtifactInputError("artifact input must be a string");
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        throw new ArtifactInputError("artifact input is empty");
+    }
+    if (trimmed.startsWith(KBDOC_PREFIX)) {
+        const id = trimmed.slice(KBDOC_PREFIX.length).trim();
+        if (!id) {
+            throw new ArtifactInputError("kbdoc: prefix requires an id");
+        }
+        return { kind: "kbdoc", id };
+    }
+    if (trimmed.startsWith(KBDOCREV_PREFIX)) {
+        const id = trimmed.slice(KBDOCREV_PREFIX.length).trim();
+        if (!id) {
+            throw new ArtifactInputError("kbdocrev: prefix requires an id");
+        }
+        return { kind: "kbdocrev", id };
+    }
+    if (trimmed.startsWith(NOTE_PREFIX)) {
+        const p = trimmed.slice(NOTE_PREFIX.length).trim();
+        if (!p) {
+            throw new ArtifactInputError("note: prefix requires a path");
+        }
+        return { kind: "note", path: p };
+    }
+    return { kind: "path", path: trimmed };
+}
+// Receipts and renderers always express ids in the canonical `kbdoc:<id>`
+// shape so audit log lookups and MCP queries can use the same string.
+function formatKbDocId(id) {
+    if (!id)
+        throw new ArtifactInputError("formatKbDocId: id is required");
+    return `${KBDOC_PREFIX}${id}`;
+}
+function formatKbDocRevId(id) {
+    if (!id)
+        throw new ArtifactInputError("formatKbDocRevId: id is required");
+    return `${KBDOCREV_PREFIX}${id}`;
+}
+// Inverse of parseArtifactInput for display. Bare paths render as-is (no
+// `note:` prefix) because the deprecation-window form is operator-typed
+// input, not output the CLI should emit.
+function formatArtifactInput(input) {
+    switch (input.kind) {
+        case "kbdoc":
+            return formatKbDocId(input.id);
+        case "kbdocrev":
+            return formatKbDocRevId(input.id);
+        case "note":
+            return `${NOTE_PREFIX}${input.path}`;
+        case "path":
+            return input.path;
+    }
+}
+// HTTP query-param shape: the intel routes that resolve operator input accept
+// either `documentId=<id>` (when the CLI parsed a kbdoc/kbdocrev) or
+// `path=<value>` (when the CLI saw a bare path or legacy note:). Centralized
+// here so command files don't reinvent the encoding.
+function toResolverQuery(input) {
+    switch (input.kind) {
+        case "kbdoc":
+            return { documentId: input.id };
+        case "kbdocrev":
+            return { revisionId: input.id };
+        case "note":
+        case "path":
+            return { path: input.path };
+    }
+}