@meetless/mla 0.1.4

package/dist/commands/kb_retime.js

@@ -0,0 +1,170 @@
+"use strict";
+// `mla kb retime <source-item-id> --effective-date <date>` (Phase 5.3).
+//
+// retime corrects the trusted EFFECTIVE DATE of a source item (a note, a diff, a
+// thread) and regenerates the derived relations it anchors. It is the operator's
+// front door to the Phase 4 correction path:
+//
+//   POST /internal/v1/kb/retime -> create_temporal_correction -> regeneration
+//
+// which honours the Option-3 invariant: an accepted relation is NEVER edited in
+// place nor physically deleted. A correction records a new anchor for the source
+// item, stales that item's live derived relations (sets invalidated_at, leaving
+// valid_at and row identity intact), and re-inserts fresh live edges under the
+// corrected anchor through the resolver. So retime edits the SOURCE ITEM, not a
+// relation; you never hand-edit a relation's valid_at.
+//
+// Mirrors the kb_promote.ts deps-injection shape: a thin public `runKbRetime` that
+// loads the real config (readKbConfig) and wires the real intelPost, while every
+// collaborator is injectable so the unit test drives it offline (no network,
+// config, or disk).
+//
+// Auth + actor: the POST carries Authorization via the shared intel HTTP layer;
+// the actor rides in the BODY (intel stamps only Authorization + X-Trace-ID,
+// never X-Meetless-Actor), so `actor` comes from cfg.actorUserId in the payload.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKbRetimeArgs = parseKbRetimeArgs;
+exports.runKbRetime = runKbRetime;
+const config_1 = require("../lib/config");
+const http_1 = require("../lib/http");
+const temporal_1 = require("../lib/temporal");
+const USAGE = "Usage: mla kb retime <source-item-id> --effective-date <date> [--reason <s>] [--anchor-type <t>] [--json]";
+const VALUE_FLAGS = new Set(["--effective-date", "--reason", "--anchor-type"]);
+const BOOLEAN_FLAGS = new Set(["--json"]);
+// Parse a single positional <source-item-id>, the required --effective-date, plus
+// optional --reason / --anchor-type / --json. A value flag with no following
+// value, a missing source id or effective date, a second positional, or an
+// unknown flag are all usage errors (the caller maps them to exit 2).
+function parseKbRetimeArgs(argv) {
+    let sourceItemId = null;
+    let effectiveDate = null;
+    let reason;
+    let anchorType;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (VALUE_FLAGS.has(a)) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("-")) {
+                throw new Error(`Missing value for ${a}. ${USAGE}`);
+            }
+            if (a === "--effective-date")
+                effectiveDate = next;
+            else if (a === "--reason")
+                reason = next;
+            else if (a === "--anchor-type")
+                anchorType = next;
+            i++;
+        }
+        else if (BOOLEAN_FLAGS.has(a)) {
+            json = true;
+        }
+        else if (a.startsWith("-")) {
+            const supported = [...VALUE_FLAGS, ...BOOLEAN_FLAGS].sort().join(", ");
+            throw new Error(`Unknown flag: ${a}. Supported: ${supported}. ${USAGE}`);
+        }
+        else if (sourceItemId === null) {
+            sourceItemId = a;
+        }
+        else {
+            throw new Error(`Unexpected argument: ${a}. ${USAGE}`);
+        }
+    }
+    if (sourceItemId === null) {
+        throw new Error(`mla kb retime requires a source item id. ${USAGE}`);
+    }
+    if (effectiveDate === null) {
+        throw new Error(`mla kb retime requires --effective-date. ${USAGE}`);
+    }
+    return { sourceItemId, effectiveDate, reason, anchorType, json };
+}
+// Surface an intel HTTP failure helpfully, mirroring kb_promote.ts's explainPromoteError.
+function explainRetimeError(err, intelUrl) {
+    if (err.status === 404) {
+        return `intel returned 404 for the retime route. The source item was not found, or this intel does not expose the KB retime endpoint.`;
+    }
+    if (err.status === 422) {
+        return `intel rejected the correction (HTTP 422): ${err.body ?? err.message}`;
+    }
+    if (err.status === 401 || err.status === 403) {
+        return `intel rejected the token (HTTP ${err.status}). Check controlToken in cli-config.json.`;
+    }
+    if (err.status === undefined) {
+        return `intel not reachable at ${intelUrl}. Is it running? Try \`mla doctor\`.`;
+    }
+    return err.message;
+}
+// Render the correction receipt in plain words. No double-dash range separators
+// (An's AI-smell rule); each line spells out what changed so an operator reads a
+// receipt, not a guess.
+function renderReceipt(r) {
+    const out = [];
+    out.push(`Retimed ${r.sourceItemId}: effective date corrected to ${r.effectiveDate}.`);
+    out.push(`  new anchor:      ${r.newAnchorId}`);
+    if (r.priorAnchorId)
+        out.push(`  prior anchor:    ${r.priorAnchorId} (superseded, kept for audit)`);
+    out.push(`  staled relations: ${r.staledRelationIds.length}`);
+    if (r.regenerated) {
+        out.push(`  regenerated:     ${r.regeneratedRelationIds.length} live edge(s) under the corrected anchor`);
+    }
+    else {
+        out.push(`  regenerated:     pending (a concurrent drainer claimed the event; it will regenerate)`);
+    }
+    out.push("");
+    out.push("retime edits the SOURCE ITEM's effective date and regenerates derived relations; it does not edit accepted relations in place.");
+    return out.join("\n");
+}
+async function runKbRetime(argv, deps) {
+    let cfg;
+    try {
+        cfg = deps?.cfg ?? (0, config_1.readKbConfig)();
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    let parsed;
+    try {
+        parsed = parseKbRetimeArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    // Validate + normalize the effective date client-side so a typo never silently
+    // anchors to "now". parseAsOf throws on anything malformed (exit 2, no POST).
+    let effectiveDate;
+    try {
+        effectiveDate = (0, temporal_1.parseAsOf)(parsed.effectiveDate);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    const post = deps?.http?.intelPost ?? http_1.intelPost;
+    const body = {
+        workspaceId: cfg.workspaceId,
+        sourceItemId: parsed.sourceItemId,
+        effectiveDate,
+        actor: cfg.actorUserId,
+    };
+    if (parsed.reason !== undefined)
+        body.reason = parsed.reason;
+    if (parsed.anchorType !== undefined)
+        body.anchorType = parsed.anchorType;
+    let res;
+    try {
+        res = (await post(cfg, "/internal/v1/kb/retime", body));
+    }
+    catch (e) {
+        const intelUrl = cfg.intelUrl || http_1.DEFAULT_INTEL_URL;
+        console.error(explainRetimeError(e, intelUrl));
+        return 1;
+    }
+    if (parsed.json) {
+        console.log(JSON.stringify(res, null, 2));
+        return 0;
+    }
+    console.log(renderReceipt(res));
+    return 0;
+}

package/dist/commands/kb_review.js

@@ -0,0 +1,391 @@
+"use strict";
+// `mla kb review <candidate-id> (--accept | --reject | --reclassify <TYPE>
+//   [--scope-section <text>] | --no-relation) [--note <text>] [--agent]`
+//
+// B5 core (notes/20260603-mla-kb-agent-proxy-and-evidence-adoption.md §3, §7.4).
+// Routes a verdict through the EXISTING control finalize primitive
+// (POST /internal/v1/relationship-candidates/<id>/{accept,reject}) -- the same
+// primitive the Console and the meetless__relationship_verdict MCP tool already
+// use. The CLI never writes the knowledge graph and never bypasses the promotion
+// gate (status==ACCEPTED && posture==LIVE is the control service's job; the CLI
+// only records the verdict, which control then transitions + propagates via outbox).
+//
+// A-2 write-side: --reclassify / --scope-section / --no-relation map to the
+// propose-correction verb (POST .../propose-correction). A correction is a
+// PROPOSED training label, not a live-graph edit: it captures "the right answer is
+// X" so a human can apply it later ("agent proposes; user applies"). Because it
+// never mutates the graph, propose-correction is ALWAYS allowed -- for a human and
+// for an automated proxy alike -- unlike accept (human-only) and reject (an agent
+// may only auto-reject mechanically-invalid candidates).
+//
+// Auto-resolution policy (P2, MVP): REJECT-ONLY. The `--agent` flag declares that an
+// automated proxy (Claude Code acting on An's behalf) is the caller:
+//   * `--accept --agent` is ALWAYS refused. Accepting a relationship is institutional
+//     memory; a wrong auto-accept manufactures false governance and poisons
+//     retrieval, which is strictly worse than leaving the edge unreviewed. Only a
+//     human may accept.
+//   * `--reject --agent` is allowed ONLY when the candidate is mechanically invalid
+//     (classifyMechanicalInvalidity); otherwise it is refused and surfaced for human
+//     review. The auto-reject reason is stamped into the verdict note for audit.
+// A human (no `--agent`) is the authority: both verbs proceed unconditionally.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKbReviewArgs = parseKbReviewArgs;
+exports.evaluateReviewPolicy = evaluateReviewPolicy;
+exports.runKbReviewWith = runKbReviewWith;
+exports.renderReviewFooter = renderReviewFooter;
+exports.renderCorrectionFooter = renderCorrectionFooter;
+exports.runKbReview = runKbReview;
+const config_1 = require("../lib/config");
+const http_1 = require("../lib/http");
+const kb_candidate_1 = require("../lib/kb-candidate");
+const recorder_1 = require("../lib/analytics/recorder");
+const review_analytics_1 = require("../lib/analytics/review-analytics");
+const USAGE = "Usage: mla kb review <candidate-id> (--accept | --reject | --reclassify <TYPE> [--scope-section <text>] | --no-relation) [--note <text>] [--agent]";
+// Validate the SHAPE of a --reclassify value and normalize it to the canonical
+// SCREAMING_SNAKE the relation-type registry uses. We deliberately do NOT check it
+// against the registry here (control is the authority; coupling the CLI to the
+// enum would risk false rejects on registry drift). A typo surfaces as a clean
+// control error after one round-trip.
+function normalizeCorrectedRelationType(raw) {
+    const t = raw.trim().toUpperCase();
+    if (!/^[A-Z][A-Z0-9_]*$/.test(t)) {
+        throw new Error(`--reclassify expects a relation type like REFINES or SUPERSEDES (got "${raw}"). ` +
+            `The authoritative set is validated by control.`);
+    }
+    return t;
+}
+function parseKbReviewArgs(argv) {
+    let candidateId;
+    let accept = false;
+    let reject = false;
+    let agent = false;
+    let note = null;
+    let reclassify;
+    let noRelation = false;
+    let scopeSection;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--accept") {
+            accept = true;
+        }
+        else if (a === "--reject") {
+            reject = true;
+        }
+        else if (a === "--agent") {
+            agent = true;
+        }
+        else if (a === "--no-relation") {
+            noRelation = true;
+        }
+        else if (a === "--note") {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error("--note requires a value");
+            note = v;
+        }
+        else if (a === "--reclassify") {
+            const v = argv[++i];
+            if (v === undefined || v.startsWith("-")) {
+                throw new Error("--reclassify requires a relation type (e.g. REFINES)");
+            }
+            reclassify = v;
+        }
+        else if (a === "--scope-section") {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error("--scope-section requires a value");
+            scopeSection = v;
+        }
+        else if (a.startsWith("-")) {
+            throw new Error(`Unknown flag: ${a}. ${USAGE}`);
+        }
+        else {
+            if (candidateId !== undefined)
+                throw new Error(`Unexpected extra argument: ${a}. ${USAGE}`);
+            candidateId = a;
+        }
+    }
+    if (candidateId === undefined)
+        throw new Error(USAGE);
+    const primaries = (accept ? 1 : 0) + (reject ? 1 : 0) + (reclassify !== undefined ? 1 : 0) + (noRelation ? 1 : 0);
+    if (primaries === 0) {
+        // Keep the legacy "--accept or --reject" phrasing (callers/tests key on it)
+        // while pointing at the new correction verbs.
+        throw new Error(`Pass one of --accept or --reject (or --reclassify <TYPE> / --no-relation to propose a correction). ${USAGE}`);
+    }
+    if (primaries > 1) {
+        throw new Error("Pass exactly one of --accept, --reject, --reclassify, or --no-relation, not several");
+    }
+    if (scopeSection !== undefined && reclassify === undefined) {
+        throw new Error("--scope-section requires --reclassify <TYPE> (a section-scoped correction still needs the corrected relation type)");
+    }
+    if (reclassify !== undefined) {
+        const correctedRelationType = normalizeCorrectedRelationType(reclassify);
+        const correction = scopeSection !== undefined
+            ? {
+                correctionKind: "SCOPE_CORRECTION",
+                correctedRelationType,
+                scopeKind: "SECTION",
+                sourceSectionPath: scopeSection,
+            }
+            : { correctionKind: "RELATION_TYPE_CORRECTION", correctedRelationType };
+        return { candidateId, verdict: "propose-correction", note, agent, correction };
+    }
+    if (noRelation) {
+        return {
+            candidateId,
+            verdict: "propose-correction",
+            note,
+            agent,
+            correction: { correctionKind: "NO_RELATION" },
+        };
+    }
+    return { candidateId, verdict: accept ? "accept" : "reject", note, agent };
+}
+// The P2 policy gate. Pure; the candidate is consulted only for the agent-reject
+// path (to classify mechanical invalidity). Returns the verdict note to persist on
+// proceed, or a refusal with an exit code and an operator-facing message.
+function evaluateReviewPolicy(opts) {
+    const { candidateId, verdict, agent, note } = opts;
+    // A-2: a correction is propose-only (no live-graph edit; a human applies it
+    // later), so it is always allowed regardless of caller. This is checked BEFORE
+    // the agent gates below precisely so an automated proxy is NOT blocked from
+    // proposing a correction the way it is blocked from accept/reject.
+    if (verdict === "propose-correction") {
+        return { action: "proceed", note: note ?? undefined };
+    }
+    // Human caller: full authority over both verbs.
+    if (!agent) {
+        return { action: "proceed", note: note ?? undefined };
+    }
+    // Automated proxy: reject-only, mechanically gated.
+    if (verdict === "accept") {
+        return {
+            action: "refuse",
+            exitCode: 2,
+            message: `Auto-accept is disallowed for an automated proxy (P2). Accepting a relationship ` +
+                `is institutional memory; a wrong auto-accept creates false governance and ` +
+                `poisons retrieval. A human must accept ${candidateId}. Surface it with ` +
+                `\`mla kb pending\` and ask the operator to run \`mla kb review ${candidateId} --accept\`.`,
+        };
+    }
+    // verdict === "reject" && agent
+    const cand = opts.candidate;
+    if (!cand) {
+        return {
+            action: "refuse",
+            exitCode: 1,
+            message: `Candidate ${candidateId} not found; cannot evaluate auto-reject eligibility.`,
+        };
+    }
+    const mech = (0, kb_candidate_1.classifyMechanicalInvalidity)(cand);
+    if (!mech.autoRejectable) {
+        return {
+            action: "refuse",
+            exitCode: 2,
+            message: `Candidate ${candidateId} is not mechanically invalid, so an automated proxy may ` +
+                `not reject it (P2: agent auto-resolution is reject-only AND limited to ` +
+                `mechanically-invalid candidates: self-edge or unsupported low-confidence). ` +
+                `Surface it for a human decision with \`mla kb pending\`.`,
+        };
+    }
+    const auto = `[auto-reject:${mech.reasonCode}] ${mech.reason}`;
+    const combined = note ? `${auto}; ${note}` : auto;
+    return { action: "proceed", note: combined };
+}
+// T7.2: emit the value/trust analytics for a RECORDED review decision
+// (mla_review_decision always; mla_contradiction only for a CONTRADICTS/SUPERSEDES
+// edge). Called AFTER a successful submission, so a recorded decision is the
+// trigger and a refused operation never emits. Fully best-effort: it resolves the
+// reviewed candidate's relation type (reusing the row the agent-reject path already
+// loaded; otherwise a best-effort fetch so the human paths still carry relation_type
+// and the contradiction signal) and records each event into the run buffer. Any
+// failure -- a fetch error, an absent run context -- is swallowed so analytics can
+// never block or revert a verdict.
+async function emitReviewAnalytics(parsed, ctx, deps, alreadyFetched) {
+    try {
+        const record = deps.record ?? recorder_1.recordAnalyticsEvent;
+        const env = deps.env ?? process.env;
+        const nowMs = deps.nowMs ?? Date.now();
+        let relationTypeId = null;
+        if (alreadyFetched !== undefined) {
+            // The agent-reject path already loaded the row; reuse it (no second fetch).
+            relationTypeId = alreadyFetched?.relationTypeId ?? null;
+        }
+        else {
+            try {
+                const c = await deps.fetchCandidate(parsed.candidateId);
+                relationTypeId = c?.relationTypeId ?? null;
+            }
+            catch {
+                // best-effort: degrade to relation_type="unknown"; still record the decision.
+            }
+        }
+        const events = (0, review_analytics_1.buildReviewAnalyticsEvents)({
+            candidateId: parsed.candidateId,
+            verdict: parsed.verdict,
+            correctionKind: parsed.correction?.correctionKind,
+            relationTypeId,
+        });
+        const recordCtx = {
+            workspaceId: ctx.workspaceId,
+            sessionId: (env.CLAUDE_CODE_SESSION_ID || "").trim() || null,
+            now: new Date(nowMs).toISOString(),
+        };
+        for (const ev of events) {
+            record(recordCtx, ev, env);
+        }
+    }
+    catch {
+        // fail-soft: a verdict must never be blocked or reverted by analytics.
+    }
+}
+async function runKbReviewWith(argv, ctx, deps) {
+    let parsed;
+    try {
+        parsed = parseKbReviewArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    // Only the agent-reject path needs the candidate row (to classify). Human verdicts
+    // and the agent-accept refusal short-circuit without a fetch.
+    let candidate;
+    if (parsed.agent && parsed.verdict === "reject") {
+        try {
+            candidate = await deps.fetchCandidate(parsed.candidateId);
+        }
+        catch (e) {
+            console.error(`Failed to load candidate ${parsed.candidateId}: ${e.message}`);
+            return 1;
+        }
+    }
+    const decision = evaluateReviewPolicy({
+        candidateId: parsed.candidateId,
+        verdict: parsed.verdict,
+        agent: parsed.agent,
+        note: parsed.note,
+        candidate,
+    });
+    if (decision.action === "refuse") {
+        console.error(decision.message);
+        return decision.exitCode;
+    }
+    // A-2: a correction takes the propose-correction boundary, not the verdict one.
+    if (parsed.verdict === "propose-correction" && parsed.correction) {
+        const cbody = {
+            workspaceId: ctx.workspaceId,
+            userId: ctx.actorUserId,
+            correction: parsed.correction,
+        };
+        if (decision.note !== undefined)
+            cbody.note = decision.note;
+        let cresult;
+        try {
+            cresult = await deps.submitCorrection(parsed.candidateId, cbody);
+        }
+        catch (e) {
+            const err = e;
+            if (err.status === 404) {
+                console.error(`Candidate ${parsed.candidateId} not found.`);
+                return 1;
+            }
+            console.error(`Failed to propose a correction for ${parsed.candidateId}: ${err.message}`);
+            return 1;
+        }
+        const footer = renderCorrectionFooter(parsed.candidateId, cresult, (0, kb_candidate_1.candidateConsoleUrl)(ctx.consoleBase, parsed.candidateId));
+        for (const line of footer)
+            console.log(line);
+        await emitReviewAnalytics(parsed, ctx, deps, candidate);
+        return 0;
+    }
+    // The propose-correction case returned above, so the only verdicts left are the
+    // two finalize verbs.
+    const verdict = parsed.verdict;
+    const body = {
+        workspaceId: ctx.workspaceId,
+        userId: ctx.actorUserId,
+    };
+    if (decision.note !== undefined)
+        body.note = decision.note;
+    let result;
+    try {
+        result = await deps.submitVerdict(parsed.candidateId, verdict, body);
+    }
+    catch (e) {
+        const err = e;
+        if (err.status === 404) {
+            console.error(`Candidate ${parsed.candidateId} not found.`);
+            return 1;
+        }
+        console.error(`Failed to record verdict for ${parsed.candidateId}: ${err.message}`);
+        return 1;
+    }
+    const verb = verdict === "accept" ? "accepted" : parsed.agent ? "auto-rejected" : "rejected";
+    const footer = renderReviewFooter(verb, parsed.candidateId, result.statusId, (0, kb_candidate_1.candidateConsoleUrl)(ctx.consoleBase, parsed.candidateId));
+    for (const line of footer)
+        console.log(line);
+    await emitReviewAnalytics(parsed, ctx, deps, candidate);
+    return 0;
+}
+// A-0 (A4 surface 1): the success footer. The CLI caller is UNKNOWN (a human and a
+// coding agent run the identical command), so an ACCEPT -- the one governed verb --
+// gets a dual-audience note: it states the accept carried the user's authority and
+// reminds an agent that the UX default is propose-first (it should not have run
+// --accept directly). A reject/auto-reject is freely allowed and gets no such note.
+function renderReviewFooter(verb, candidateId, statusId, consoleUrl) {
+    const lines = [`${verb} relationship candidate ${candidateId} (now ${statusId}).`, `  ${consoleUrl}`];
+    if (verb === "accepted") {
+        lines.push("Recorded under the user's authority (a governed change). If you are an agent, the default is to propose accepts and let the user confirm rather than run --accept directly.");
+    }
+    return lines;
+}
+// A-2: the propose-correction footer. A correction is propose-only, so it must NOT
+// borrow the accept footer's "user's authority" language: nothing in the live graph
+// changed. It names the proposed correction, points at the console, and states that
+// a human applies it later (and flags a deduped re-proposal so the caller does not
+// think a fresh record was created).
+function renderCorrectionFooter(candidateId, result, consoleUrl) {
+    const what = result.correctionKindId === "NO_RELATION"
+        ? "no relation (the edge should not exist)"
+        : `${result.correctedRelationTypeKey}`;
+    const lines = [
+        `proposed correction for relationship candidate ${candidateId}: ${what} ` +
+            `(${result.curationStatusId.toLowerCase()}, not yet applied to the graph).`,
+        `  ${consoleUrl}`,
+    ];
+    if (result.deduped) {
+        lines.push("This matches a correction already proposed for this candidate, so no new record was created (deduped).");
+    }
+    lines.push("A human applies or dismisses proposed corrections; this did not change the live knowledge graph.");
+    return lines;
+}
+// Public entrypoint: wires real config + the control HTTP boundary.
+async function runKbReview(argv) {
+    let cfg;
+    try {
+        cfg = (0, config_1.readKbConfig)();
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    const consoleBase = (0, config_1.getConsoleUrl)(cfg);
+    const deps = {
+        fetchCandidate: async (id) => {
+            try {
+                const r = await (0, http_1.get)(cfg, `/internal/v1/relationship-candidates/${encodeURIComponent(id)}?workspaceId=${encodeURIComponent(cfg.workspaceId)}`, 10000);
+                return r.candidate ?? null;
+            }
+            catch (e) {
+                if (e.status === 404)
+                    return null;
+                throw e;
+            }
+        },
+        submitVerdict: async (id, verdict, body) => (0, http_1.post)(cfg, `/internal/v1/relationship-candidates/${encodeURIComponent(id)}/${verdict}`, body, 15000),
+        submitCorrection: async (id, body) => (0, http_1.post)(cfg, `/internal/v1/relationship-candidates/${encodeURIComponent(id)}/propose-correction`, body, 15000),
+    };
+    return runKbReviewWith(argv, { workspaceId: cfg.workspaceId, actorUserId: cfg.actorUserId, consoleBase }, deps);
+}