@meetless/mla 0.1.4

package/dist/commands/kb.js

@@ -0,0 +1,375 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.isReviewListInvocation = isReviewListInvocation;
+exports.pendingAliasArgs = pendingAliasArgs;
+exports.runKb = runKb;
+const config_1 = require("../lib/config");
+const http_1 = require("../lib/http");
+const kb_add_1 = require("./kb_add");
+const kb_show_1 = require("./kb_show");
+const kb_reingest_1 = require("./kb_reingest");
+const kb_forget_1 = require("./kb_forget");
+const kb_purge_1 = require("./kb_purge");
+const kb_move_1 = require("./kb_move");
+const kb_pending_1 = require("./kb_pending");
+const kb_review_1 = require("./kb_review");
+const kb_personal_1 = require("./kb_personal");
+const kb_promote_1 = require("./kb_promote");
+const kb_retime_1 = require("./kb_retime");
+const kb_revision_1 = require("./kb_revision");
+// Legacy inspect parser. Only handles `mla kb summary` and `mla kb dump`; the
+// six curation subcommands (add/show/reingest/forget/purge/move) are routed by
+// `runKb` BEFORE this is called and each owns its own arg parser inside its own
+// commands/kb_*.ts module.
+function parseArgs(argv) {
+    const sub = argv[0];
+    if (sub !== "summary" && sub !== "dump") {
+        throw new Error(`Usage: mla kb summary [--json] | mla kb dump [--markdown] [--json]`);
+    }
+    const out = { sub, json: false, markdown: false };
+    for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--json")
+            out.json = true;
+        else if (a === "--markdown")
+            out.markdown = true;
+        else
+            throw new Error(`Unknown flag for \`mla kb ${sub}\`: ${a}`);
+    }
+    return out;
+}
+function n(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+// The three buckets of §5.1, plus the Control read-projection mirror. Labels are
+// deliberately honest about provenance: the notes/LDM ingest writes ONLY the
+// Sources layer (chunks + chunk_fts). The graph layer (entities /
+// knowledge_relations / claim-kind entities) is written by the claims extractor
+// (`--pipeline=claims`) and the relationship-promotion loop, NOT by notes
+// ingest, so it reads 0 for a notes-only workspace by design. Conflating the two
+// under an "accepted/live, promoted from sources" label is what made the old
+// output look broken.
+function bucketLines(c) {
+    return {
+        sources: [
+            `chunks (Weaviate):        ${n(c.chunks)}`,
+            `chunk_fts (lexical):      ${n(c.chunk_fts)}`,
+        ],
+        graph: [
+            `entities (nodes):         ${n(c.graph_nodes)}`,
+            `knowledge_relations:      ${n(c.graph_edges)}`,
+            `claim-kind entities:      ${n(c.claims)}`,
+        ],
+        ops: [
+            `decision diffs:           ${n(c.ops_decision_diffs)}`,
+            `coordination cases:       ${n(c.ops_coordination_cases)}`,
+            `relationship candidates:  ${n(c.ops_relationship_candidates)}`,
+            `workflow audit:           ${n(c.ops_workflow_audit)}`,
+            `outbox pending:           ${n(c.outbox_pending)}`,
+        ],
+    };
+}
+const SOURCES_LABEL = "Sources (ingested via notes/LDM pipeline):";
+const GRAPH_LABEL = "Internalized graph (claims + relationship pipeline; not written by notes ingest):";
+const OPS_LABEL = "Control read projection:";
+// withDumpPointer is true only for the standalone `summary` view, where the
+// closing line nudges the reader toward `dump`. In `dump` the per-source
+// listing follows immediately below, so repeating "run dump" there would tell
+// the reader to run the command they are already looking at.
+function renderSummary(c, withDumpPointer = true) {
+    const b = bucketLines(c);
+    const out = [];
+    out.push(`Knowledge base summary (workspace: ${c.workspaceId})`);
+    out.push("");
+    out.push(SOURCES_LABEL);
+    b.sources.forEach((l) => out.push(`  ${l}`));
+    out.push(GRAPH_LABEL);
+    b.graph.forEach((l) => out.push(`  ${l}`));
+    out.push(OPS_LABEL);
+    b.ops.forEach((l) => out.push(`  ${l}`));
+    if (withDumpPointer) {
+        out.push("");
+        out.push("Counts only. Run `mla kb dump` to list the ingested sources (note paths + chunk counts).");
+    }
+    return out.join("\n");
+}
+function renderSourcesPlain(s) {
+    const out = [];
+    out.push(`Ingested sources (${s.total}):`);
+    if (s.total === 0) {
+        out.push("  none yet (nothing ingested into chunk_fts for this workspace).");
+        return out.join("\n");
+    }
+    for (const src of s.sources) {
+        const when = src.lastIngestedAt ?? "unknown";
+        out.push(`  ${src.documentId}`);
+        out.push(`    ${src.parentKind}, ${n(src.chunkCount)} chunks, last ingested ${when}`);
+    }
+    return out.join("\n");
+}
+function renderDumpPlain(c, s) {
+    return [renderSummary(c, false), "", renderSourcesPlain(s)].join("\n");
+}
+function mdRow(l) {
+    const idx = l.lastIndexOf(":");
+    const label = l.slice(0, idx).trim();
+    const val = l.slice(idx + 1).trim();
+    return `| ${label} | ${val} |`;
+}
+function mdSection(title, lines) {
+    return [`### ${title}`, "", "| substrate | count |", "| --- | --- |", ...lines.map(mdRow), ""].join("\n");
+}
+function mdSources(s) {
+    const head = [`### Ingested sources (${s.total})`, ""];
+    if (s.total === 0) {
+        return [...head, "_none yet (nothing ingested into chunk_fts for this workspace)._", ""].join("\n");
+    }
+    const rows = s.sources.map((src) => `| ${src.documentId} | ${src.parentKind} | ${n(src.chunkCount)} | ${src.lastIngestedAt ?? "unknown"} |`);
+    return [
+        ...head,
+        "| source | kind | chunks | last ingested |",
+        "| --- | --- | --- | --- |",
+        ...rows,
+        "",
+    ].join("\n");
+}
+function renderDumpMarkdown(c, s) {
+    const b = bucketLines(c);
+    const ts = new Date().toISOString();
+    return [
+        `# Meetless knowledge base snapshot`,
+        "",
+        `- workspace: \`${c.workspaceId}\``,
+        `- generated: ${ts}`,
+        "",
+        mdSection("Sources (ingested via notes/LDM pipeline)", b.sources),
+        mdSection("Internalized graph (claims + relationship pipeline, not notes ingest)", b.graph),
+        mdSection("Control read projection", b.ops),
+        mdSources(s),
+        `> Sources are listed per-document from chunk_fts. The graph + control`,
+        `> projection layers expose counts only (their per-item read endpoints`,
+        `> remain deferred). Counts wrap \`/v1/debug/substrate_counts\`; the source`,
+        `> list wraps \`/v1/debug/ingested_sources\`.`,
+        "",
+    ].join("\n");
+}
+function explainIntelError(err, intelUrl) {
+    if (err.status === 404) {
+        return (`intel returned 404 for a /v1/debug route. Those routes are mounted ` +
+            `only when intel runs with SERVER_ENV != production; the KB inspector ` +
+            `needs a non-production intel.`);
+    }
+    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;
+}
+// The user-facing `mla kb` catalog. This is the help surface an operator (or
+// an agent) reads to decide WHICH kb subcommand to run, so it has to teach the
+// one fact that gets the commands confused: posture (grounding) and
+// relationships (coherence) are two independent axes, and `kb promote` only
+// touches the first. The accurate model used to live ONLY in a code comment
+// above; surfacing it here is the root-cause fix for "add/promote/review get
+// mixed up". Keep the word "Usage" present: the bad-subcommand error path
+// re-emits this block and a test locks that contract.
+const KB_USAGE = `mla kb: Knowledge Base curation, grounding, and relationship review.
+
+Two independent axes govern every KB doc. Do not conflate them:
+
+  posture (grounding): does the agent retrieve + cite this doc?
+      LIVE = grounded, agent-visible.  SHADOW = stored, NOT grounded.
+      Posture defaults BY provenance at ingest:
+          human_authored   -> LIVE    (grounded immediately; no extra step)
+          agent_distilled, tool_emitted, external_imported,
+          external_scraped -> SHADOW  (promote later with \`mla kb promote\`)
+      So \`mla kb add --provenance human_authored\` already remembers a
+      decision: it lands LIVE. \`kb promote\` ONLY flips a SHADOW Personal-KB
+      doc to LIVE; it is NOT how a human-authored doc becomes grounded.
+
+  relationships (coherence): how does this doc relate to existing docs?
+      Edges (SUPERSEDES / CONTRADICTS / REFINES / REFERENCES) are proposed as
+      candidates and decided via \`kb review\` (list, then verdict). Reviewing an
+      edge records how docs relate; it does NOT change grounding (posture).
+
+Relations also carry TIME. Two temporal axes, never conflated:
+
+  valid-time: when a relation is TRUE in the world (its valid-from / valid-until
+      window). \`mla kb show --as-of <date>\` and \`mla ask --as-of <date>\` answer
+      point-in-time: relations not yet valid at that instant, or carried on an
+      untrusted clock, are excluded. Validity is SEPARATE from posture and from
+      relationship review.
+
+  observation-time: when Meetless recorded the relation. A trusted clock means
+      valid-time came from an author stamp or document date; an approximate clock
+      means we only know when we observed it, not when it became true. \`kb show\`
+      prints each relation's window plus this trust so observation never reads as
+      validity.
+
+Usage:
+  ingest + curation
+    mla kb add <path> --mode file|corpus --provenance <kind>
+                      [--workspace <id>] [--vault-root <dir>]
+                      [--profile <p>] [--glob <g>] [--ingest-run-id <id>]
+                      [--queue] [--open]
+                      (born PENDING; --provenance is advisory, server derives trust)
+    mla kb show <kbdoc:<id>|note:<path>|<path>>
+                      [--posture both|LIVE|SHADOW] [--as-of <date>]
+                      [--all] [--json] [--open]
+    mla kb reingest <kbdoc:<id>|note:<path>|<path>> [--path <new-path>] [--reason <s>]
+    mla kb accept <kbdoc:<id>|<doc-id>> [--reason <s>] [--json]
+    mla kb reject <kbdoc:<id>|<doc-id>> [--reason <s>] [--json]
+                      (resolve a revision a reingest parked at SHADOW_PENDING_REVIEW
+                       because the doc has promoted edges. accept makes the pending
+                       revision live (it starts grounding answers, the old one is
+                       superseded); reject discards it and keeps the old revision
+                       serving. Acts on the doc's single pending revision: this is the
+                       grounding-BYTES axis, separate from \`kb promote\` (posture) and
+                       from \`kb review\` (which decides relationship edges, NOT
+                       revisions, despite also taking --accept / --reject).)
+    mla kb forget <kbdoc:<id>|note:<path>|<path>> [--reason <s>]
+    mla kb purge <kbdoc:<id>|note:<path>|<path>> --reason <s> [--force]
+    mla kb move <kbdoc:<id>|note:<path>|<path>> <new-path> [--reason <s>]
+    mla kb retime <source-item-id> --effective-date <date>
+                      [--reason <s>] [--anchor-type <t>] [--json]
+                      (correct the source item's effective date; regenerates its
+                       derived relations through the correction path. Edits the
+                       SOURCE ITEM, not a relation: an accepted relation is never
+                       edited in place nor deleted.)
+
+  grounding (posture)
+    mla kb promote <doc-id>          promote a SHADOW Personal-KB doc to LIVE
+    mla kb promote --reject <doc-id> decline the promotion; leaves it SHADOW, untouched
+    mla kb personal list             this actor's own SHADOW Personal-KB docs
+    mla kb personal show <id>        inspect one (reuses \`mla kb show\`)
+
+  relationship review
+    mla kb review                              list the queue (defaults to your current session)
+    mla kb review --all                        list the full workspace queue
+    mla kb review --session <sid|current|latest>  list a specific session's candidates
+    mla kb review [scope] --json               structured output (with agent policy + scope)
+    mla kb review <candidate-id> --accept | --reject [--note <text>] [--agent]
+                                               record a verdict (--accept is human-only)
+
+  inspect
+    mla kb summary [--json]                substrate counts for this workspace
+    mla kb dump [--markdown] [--json]      counts + one row per ingested source`;
+// Overload boundary for the `review` verb: a leading candidate id means "record a
+// verdict on this one"; anything else (no args, or a leading flag) means "list the
+// review queue". Candidate ids are CUIDs (no leading dash) and are passed first in
+// every documented usage.
+function isReviewListInvocation(argv) {
+    return argv.length === 0 || argv[0].startsWith("-");
+}
+// `pending` is the deprecated alias for the listing. Historically it was
+// workspace-wide, so inject --all to keep that default, but ONLY when the caller
+// passed no explicit scope (so old `pending --doc x` / `pending --session y` keep
+// working instead of tripping the mutual-exclusivity guard).
+function pendingAliasArgs(argv) {
+    const hasScope = argv.includes("--all") || argv.includes("--session") || argv.includes("--doc");
+    return hasScope ? argv : ["--all", ...argv];
+}
+// Curation subcommand router (kb v2.3). Each subcommand owns its own arg
+// parser + exit codes inside commands/kb_*.ts. summary/dump fall through to
+// the legacy inspect handler below.
+async function runKb(argv) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    // Help is workspace-free: print the full catalog to stdout, exit 0. This is
+    // reached by `mla kb`, `mla kb help`, and `mla kb --help/-h`.
+    if (sub === undefined || sub === "help" || sub === "--help" || sub === "-h") {
+        console.log(KB_USAGE);
+        return 0;
+    }
+    switch (sub) {
+        case "add":
+            return (0, kb_add_1.runKbAdd)(rest);
+        case "show":
+            return (0, kb_show_1.runKbShow)(rest);
+        case "reingest":
+            return (0, kb_reingest_1.runKbReingest)(rest);
+        case "forget":
+            return (0, kb_forget_1.runKbForget)(rest);
+        case "purge":
+            return (0, kb_purge_1.runKbPurge)(rest);
+        case "move":
+            return (0, kb_move_1.runKbMove)(rest);
+        case "review":
+            return isReviewListInvocation(rest) ? (0, kb_pending_1.runKbReviewList)(rest) : (0, kb_review_1.runKbReview)(rest);
+        case "pending":
+            return (0, kb_pending_1.runKbReviewList)(pendingAliasArgs(rest));
+        case "personal":
+            return (0, kb_personal_1.runKbPersonal)(rest);
+        case "promote":
+        // `share` is the deprecated alias for `promote` (renamed because "share"
+        // read as "invite a teammate"; the verb only flips SHADOW -> LIVE posture).
+        // Kept routing so existing hooks/scripts/muscle-memory keep working; it is
+        // intentionally NOT advertised in the catalog, exactly like `pending`.
+        case "share":
+            return (await (0, kb_promote_1.runKbPromote)(rest)).code;
+        case "retime":
+            return (0, kb_retime_1.runKbRetime)(rest);
+        case "accept":
+            return (0, kb_revision_1.runKbAccept)(rest);
+        case "reject":
+            return (0, kb_revision_1.runKbReject)(rest);
+    }
+    // Anything that is not a routed subcommand and not summary/dump is unknown.
+    // Emit the full catalog (not the old summary|dump-only line, which hid every
+    // curation command) on stderr, and do it WITHOUT requiring a workspace so the
+    // error is the same whether or not the folder is activated.
+    if (sub !== "summary" && sub !== "dump") {
+        console.error(`unknown \`mla kb\` subcommand: ${sub}\n`);
+        console.error(KB_USAGE);
+        return 2;
+    }
+    const cfg = (0, config_1.loadWorkspaceConfig)();
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    const intelUrl = cfg.intelUrl || http_1.DEFAULT_INTEL_URL;
+    const qs = new URLSearchParams({ workspaceId: cfg.workspaceId }).toString();
+    let counts;
+    try {
+        counts = await (0, http_1.intelGet)(cfg, `/v1/debug/substrate_counts?${qs}`, 10000);
+    }
+    catch (e) {
+        console.error(explainIntelError(e, intelUrl));
+        return 1;
+    }
+    if (args.sub === "summary") {
+        if (args.json) {
+            console.log(JSON.stringify(counts, null, 2));
+            return 0;
+        }
+        console.log(renderSummary(counts));
+        return 0;
+    }
+    // dump: fetch the per-source listing too.
+    let sources;
+    try {
+        sources = await (0, http_1.intelGet)(cfg, `/v1/debug/ingested_sources?${qs}`, 10000);
+    }
+    catch (e) {
+        console.error(explainIntelError(e, intelUrl));
+        return 1;
+    }
+    if (args.json) {
+        console.log(JSON.stringify({ counts, sources }, null, 2));
+        return 0;
+    }
+    if (args.markdown) {
+        console.log(renderDumpMarkdown(counts, sources));
+        return 0;
+    }
+    console.log(renderDumpPlain(counts, sources));
+    return 0;
+}