@vellumai/assistant 0.8.5 → 0.8.7

package/src/cli/commands/memory-v3.ts

@@ -1,316 +1,281 @@
 /**
  * `assistant memory v3` CLI subgroup.
  *
- * Operator-facing read-only inspection of the v3 memory tree — the DAG overlay
- * the v2 → v3 data-migration hand-authors over the flat concept pages.
+ * Operator-facing tree-gardening + core-editing subcommands for the v3 memory
+ * subsystem (leaf-tree activation model). The daemon owns the live tree, so the
+ * mutating verbs route through `cliIpcCall` to handlers that run inside the
+ * assistant process (where the in-memory lanes can be invalidated after a
+ * write). The read-only `health` report and the `set-core` cost preview also
+ * route through the daemon so it stays the single source of truth for the live
+ * workspace tree.
  *
  * Subcommands:
  *
- *   - `validate` — print a structural health report (dangling refs, orphan
- *     pages, cycles, stale indexes, unknown edge targets). Exits non-zero when
- *     any defect is found so it is scriptable as a check.
- *   - `tree` — print the tree as an indented outline rooted at the tree root,
- *     marking shared-DAG re-entries.
- *   - `simulate` — dry-run the v3 retrieval loop against an ad-hoc query and
- *     print the per-pass descent trace plus the lane-grouped selection.
+ *   - `health` — print the structural health report (read-only).
+ *   - `reconcile` — v1 convergence pass: rewrites any dangling page/core ref to
+ *     the current on-disk tree and prunes stale core entries. It does NOT yet
+ *     detect renames/moves/splits — that requires a captured prior leaf
+ *     snapshot (a follow-up), so `renames` is always empty in v1.
+ *   - `set-core` — add/remove always-on core leaves. Validates that every added
+ *     leaf exists, previews the resulting always-on page count, and writes only
+ *     on `--yes`.
+ *   - `rebuild-index` — invalidate the v3 lanes so the next turn rebuilds.
  *
- * All are read-only: they mutate nothing. `validate`/`tree` run no LLM;
- * `simulate` invokes the loop (filter + gate LLM calls) but persists nothing.
- * `--json` emits the raw daemon payload for any subcommand.
+ * Deferred to follow-ups: thin `add-leaf` / `rename-leaf` / `delete-leaf`
+ * wrappers (edit the leaf file[s] then reconcile).
  */
 
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-
 import type { Command } from "commander";
 
 import { cliIpcCall } from "../../ipc/cli-client.js";
 import type {
-  MemoryV3SimulateResult,
-  MemoryV3TreeResult,
-  MemoryV3ValidateResult,
+  MemoryV3HealthResult,
+  MemoryV3RebuildIndexResult,
+  MemoryV3ReconcileResult,
+  MemoryV3SetCoreResult,
 } from "../../runtime/routes/memory-v3-routes.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
-import {
-  renderLlmCalls,
-  renderSimulation,
-  renderTree,
-  renderValidationReport,
-  reportHasDefects,
-} from "./memory-v3-render.js";
 
-/** Valid lane names accepted by `--lanes` (matches memory.v3.lanes keys). */
-const V3_LANE_NAMES = ["hot", "sparse", "dense", "tree", "edges"] as const;
+/** Commander collector for a repeatable option: accumulates each value. */
+function collect(val: string, acc: string[]): string[] {
+  acc.push(val);
+  return acc;
+}
 
 export function registerMemoryV3Command(program: Command): void {
-  // Reuse an existing `memory` parent if a sibling registrar (e.g. v2)
-  // attached it first; otherwise create one. Keeps registration order between
+  // Reuse an existing `memory` parent if some other registrar attached to it
+  // first; otherwise create one. This keeps the registration order between
   // sibling memory registrars unconstrained.
   const memory =
     program.commands.find((c) => c.name() === "memory") ??
-    program
-      .command("memory")
-      .description("Manage the memory subsystem (concept-page model)");
+    program.command("memory").description("Manage the memory subsystem");
 
   registerCommand(memory, {
     name: "v3",
     transport: "ipc",
-    description: "Memory v3 subsystem operations (tree-DAG overlay)",
+    description: "Memory v3 tree-gardening and core-editing (leaf-tree model)",
     build: (v3) => {
       v3.addHelpText(
         "after",
         `
-The v3 memory subsystem layers a hand-authored DAG of tree nodes over the
-flat v2 concept pages. Each node lives under /workspace/memory/tree/ and
-its frontmatter 'children' list references sub-nodes (node:<id>) and leaf
-concept pages (page:<slug>). The structure is authored by the v2 → v3
-data-migration, so these subcommands are read-only inspection only — they
-mutate nothing and run no LLM.
+The v3 memory subsystem organizes concept pages under a curated leaf tree
+(/workspace/memory/v3/data/) and pins an always-on "core" set of leaves.
+These commands garden that tree safely: each mutating verb snapshots and
+fail-closed validates before committing, and invalidates the live lanes so
+the next turn rebuilds from the reconciled state.
 
 Examples:
-  $ assistant memory v3 validate
-  $ assistant memory v3 tree
-  $ assistant memory v3 tree --json | jq '.nodes | length'
-  $ assistant memory v3 simulate -q "what should we ship next"`,
+  $ assistant memory v3 health
+  $ assistant memory v3 set-core --add domain-a/topic-x
+  $ assistant memory v3 set-core --remove domain-a/topic-y --yes
+  $ assistant memory v3 reconcile
+  $ assistant memory v3 rebuild-index`,
       );
 
-      // ── validate ──────────────────────────────────────────────────────────
+      // ── health ────────────────────────────────────────────────────────────
 
-      v3.command("validate")
-        .description(
-          "Print a structural health report of the v3 tree (read-only)",
-        )
-        .option("--json", "Emit raw JSON instead of a formatted report")
+      v3.command("health")
+        .description("Print the v3 structural health report (read-only)")
+        .option("--json", "Emit raw JSON instead of the rendered report")
         .addHelpText(
           "after",
           `
-Walks the hand-authored v3 tree DAG and reports:
-  - Dangling child refs (node:/page: targets that do not exist)
-  - Orphan pages (concept pages not reachable from the tree root)
-  - Cycles (back-edges in the node:/node: adjacency)
-  - Stale indexes (a node older than a child it composes)
-  - Unknown edge targets (page edges: pointing at a missing slug)
-
-Read-only — mutates nothing. Exits non-zero if any defect is reported, so it
-is usable as a pre-flight check while the v2 → v3 migration is in flight.
+Loads the live leaf tree + core set and reports where the taxonomy has
+drifted from the page graph: unassigned slugs, dangling refs, novel
+clusters, and over/under-sized leaves. Read-only — no writes. Prints
+"all green" when no maintenance is warranted.
 
 Examples:
-  $ assistant memory v3 validate
-  $ assistant memory v3 validate --json | jq '.orphanPageCount'`,
+  $ assistant memory v3 health
+  $ assistant memory v3 health --json | jq '.counts'`,
         )
         .action(async (opts: { json?: boolean }) => {
-          const result = await cliIpcCall<MemoryV3ValidateResult>(
-            "memory_v3_validate",
+          const result = await cliIpcCall<MemoryV3HealthResult>(
+            "memory_v3_health",
             { body: {} },
           );
-
           if (!result.ok) {
-            log.error(result.error ?? "Failed to validate memory v3 tree");
+            log.error(result.error ?? "Failed to compute v3 health");
             process.exitCode = 1;
             return;
           }
-
-          const report = result.result!;
-
+          const payload = result.result!;
           if (opts.json === true) {
-            log.info(JSON.stringify(report, null, 2));
-          } else {
-            log.info(renderValidationReport(report));
-          }
-
-          if (reportHasDefects(report)) {
-            process.exitCode = 1;
+            log.info(JSON.stringify(payload, null, 2));
+            return;
           }
+          log.info(
+            payload.rendered === ""
+              ? "memory-v3 health: all green"
+              : payload.rendered,
+          );
         });
 
-      // ── tree ──────────────────────────────────────────────────────────────
+      // ── reconcile ─────────────────────────────────────────────────────────
 
-      v3.command("tree")
+      v3.command("reconcile")
         .description(
-          "Print the v3 tree as an indented outline from the root (read-only)",
+          "v1 convergence/prune pass over page/core refs (no rename detection yet)",
         )
-        .option("--json", "Emit raw JSON instead of a formatted tree")
+        .option("--json", "Emit raw JSON instead of a formatted summary")
         .addHelpText(
           "after",
           `
-Descends the v3 tree depth-first from its root node, printing one line per
-node:/page: ref with indentation by depth. A node reached more than once
-(shared DAG sub-node or a cycle back-edge) is printed once with a re-entry
-marker rather than re-expanded, so output is finite. Nodes that exist on disk
-but are unreachable from the root are listed separately.
-
-Read-only — mutates nothing.
+Runs a convergence pass over the leaf tree: rewrites any page leaves:
+frontmatter or core.json entry that dangles to a path the current on-disk
+tree no longer has, and prunes stale core entries. Fail-closed: snapshots
+before mutating and rolls back if any dangling reference survives
+validation. On success the v3 lanes are invalidated.
+
+Limitation: v1 cannot detect renames/moves/splits. The reconciler diffs
+the current tree against itself (there is no captured "before" snapshot),
+so renames always report as empty and a true rename surfaces as a
+delete + add. Full rename/move/split detection requires persisting a prior
+leaf snapshot and is a planned follow-up.
 
 Examples:
-  $ assistant memory v3 tree
-  $ assistant memory v3 tree --json | jq '.root'`,
+  $ assistant memory v3 reconcile
+  $ assistant memory v3 reconcile --json | jq '.prunedCore'`,
         )
         .action(async (opts: { json?: boolean }) => {
-          const result = await cliIpcCall<MemoryV3TreeResult>(
-            "memory_v3_tree",
-            {
-              body: {},
-            },
+          const result = await cliIpcCall<MemoryV3ReconcileResult>(
+            "memory_v3_reconcile",
+            { body: {} },
           );
-
           if (!result.ok) {
-            log.error(result.error ?? "Failed to read memory v3 tree");
+            log.error(result.error ?? "Failed to reconcile the v3 tree");
             process.exitCode = 1;
             return;
           }
-
-          const view = result.result!;
-
+          const payload = result.result!;
           if (opts.json === true) {
-            log.info(JSON.stringify(view, null, 2));
+            log.info(JSON.stringify(payload, null, 2));
             return;
           }
-
-          log.info(renderTree(view));
+          log.info(
+            `Renamed: ${payload.renames.length === 0 ? "none" : payload.renames.length}`,
+          );
+          for (const r of payload.renames) {
+            log.info(`  - ${r.oldPath} → ${r.newPath}`);
+          }
+          log.info(
+            `Deleted: ${payload.deleted.length === 0 ? "none" : payload.deleted.join(", ")}`,
+          );
+          log.info(
+            `Pruned core: ${payload.prunedCore.length === 0 ? "none" : payload.prunedCore.join(", ")}`,
+          );
         });
 
-      // ── simulate ────────────────────────────────────────────────────────────
+      // ── set-core ──────────────────────────────────────────────────────────
 
-      v3.command("simulate")
+      v3.command("set-core")
         .description(
-          "Dry-run the v3 retrieval loop against an ad-hoc query (read-only)",
-        )
-        .requiredOption(
-          "-q, --query <text>",
-          "User query to run a single synthetic retrieval turn against",
-        )
-        .option(
-          "--pass-cap <n>",
-          "Override memory.v3.passCap for this run (positive integer)",
+          "Add/remove always-on core leaves (previews cost; writes on --yes)",
         )
         .option(
-          "--lanes <list>",
-          `Restrict to a comma-separated allowlist of lanes (others off): ${V3_LANE_NAMES.join(", ")}`,
+          "--add <leaf>",
+          "Leaf path to add to the always-on core set (repeatable)",
+          collect,
+          [] as string[],
         )
-        .option("--json", "Emit raw JSON instead of a formatted report")
         .option(
-          "--show-llm",
-          "Print the full input + output of every v3 LLM call (filter / descender / gate)",
-        )
-        .option(
-          "--dump-llm <dir>",
-          "Write one JSON file per v3 LLM call into <dir> (full request + raw response)",
+          "--remove <leaf>",
+          "Leaf path to remove from the always-on core set (repeatable)",
+          collect,
+          [] as string[],
         )
+        .option("--yes", "Apply the change (otherwise preview only)")
+        .option("--json", "Emit raw JSON instead of a formatted summary")
         .addHelpText(
           "after",
           `
-Runs the v3 multi-lane bounded-descent loop read-only against the live page
-index + tree DAG, building a single synthetic turn from the query plus the live
-NOW context. Prints the per-pass descent trace (scouts / tree levels / edge
-expansions / gate verdict) and the final selection grouped by provenance lane.
-
-The loop is invoked directly — it does NOT require memory.v3.enabled or
-memory.v3.shadow, so you can probe v3 retrieval before the flags flip. Writes
-nothing (co-activation persistence is forced off), but each pass still spends
-the loop's dense-filter + gate LLM calls, so pass-cap is the cost knob.
+Edits the always-on core leaf set in core.json. Every --add entry must
+exist in the live tree (unknown leaves are rejected). Without --yes this
+PREVIEWS the resulting core set and the number of unique page slugs it
+would pin always-on, WITHOUT writing. Pass --yes to persist and invalidate
+the lanes.
 
 Examples:
-  $ assistant memory v3 simulate -q "what should we ship next"
-  $ assistant memory v3 simulate -q "..." --lanes tree,edges
-  $ assistant memory v3 simulate -q "..." --pass-cap 1 --json | jq '.selectedSlugs'
-  $ assistant memory v3 simulate -q "..." --show-llm
-  $ assistant memory v3 simulate -q "..." --dump-llm /tmp/v3-calls`,
+  $ assistant memory v3 set-core --add domain-a/topic-x        # preview
+  $ assistant memory v3 set-core --add domain-a/topic-x --yes  # apply
+  $ assistant memory v3 set-core --remove domain-b/topic-z --yes`,
         )
         .action(
           async (opts: {
-            query: string;
-            passCap?: string;
-            lanes?: string;
+            add: string[];
+            remove: string[];
+            yes?: boolean;
             json?: boolean;
-            showLlm?: boolean;
-            dumpLlm?: string;
           }) => {
-            let passCap: number | undefined;
-            if (opts.passCap !== undefined) {
-              const parsed = Number(opts.passCap);
-              if (!Number.isInteger(parsed) || parsed < 1) {
-                log.error(
-                  `--pass-cap must be a positive integer (got "${opts.passCap}")`,
-                );
-                process.exitCode = 1;
-                return;
-              }
-              passCap = parsed;
-            }
-
-            let lanes: string[] | undefined;
-            if (opts.lanes !== undefined) {
-              const requested = opts.lanes
-                .split(",")
-                .map((s) => s.trim())
-                .filter((s) => s.length > 0);
-              const invalid = requested.filter(
-                (l) =>
-                  !V3_LANE_NAMES.includes(l as (typeof V3_LANE_NAMES)[number]),
-              );
-              if (invalid.length > 0) {
-                log.error(
-                  `--lanes contains unknown lane(s): ${invalid.join(", ")}. Valid: ${V3_LANE_NAMES.join(", ")}`,
-                );
-                process.exitCode = 1;
-                return;
-              }
-              if (requested.length === 0) {
-                log.error("--lanes must list at least one lane");
-                process.exitCode = 1;
-                return;
-              }
-              lanes = requested;
+            if (opts.add.length === 0 && opts.remove.length === 0) {
+              log.error("Pass at least one --add or --remove leaf path.");
+              process.exitCode = 1;
+              return;
             }
 
-            const result = await cliIpcCall<MemoryV3SimulateResult>(
-              "memory_v3_simulate",
+            const result = await cliIpcCall<MemoryV3SetCoreResult>(
+              "memory_v3_set_core",
               {
                 body: {
-                  query: opts.query,
-                  ...(passCap !== undefined ? { passCap } : {}),
-                  ...(lanes !== undefined ? { lanes } : {}),
+                  add: opts.add,
+                  remove: opts.remove,
+                  write: opts.yes === true,
                 },
               },
             );
-
             if (!result.ok) {
-              log.error(result.error ?? "Failed to simulate v3 retrieval");
+              log.error(result.error ?? "Failed to update the v3 core set");
               process.exitCode = 1;
               return;
             }
-
             const payload = result.result!;
             if (opts.json === true) {
               log.info(JSON.stringify(payload, null, 2));
               return;
             }
-            log.info(renderSimulation(payload));
-
-            log.info("");
             log.info(
-              renderLlmCalls(payload.llmCalls, { full: opts.showLlm === true }),
+              `Core leaves (${payload.nextCore.length}): ${
+                payload.nextCore.length === 0
+                  ? "none"
+                  : payload.nextCore.join(", ")
+              }`,
             );
-
-            if (opts.dumpLlm !== undefined) {
-              mkdirSync(opts.dumpLlm, { recursive: true });
-              for (const call of payload.llmCalls) {
-                const nodePart = call.node
-                  ? `-${call.node.replace(/\//g, "_")}`
-                  : "";
-                const file = join(
-                  opts.dumpLlm,
-                  `pass${call.pass}-${call.lane}${nodePart}.json`,
-                );
-                writeFileSync(file, JSON.stringify(call, null, 2));
-              }
-              log.info(
-                `\nWrote ${payload.llmCalls.length} LLM-call file(s) to ${opts.dumpLlm}`,
-              );
+            log.info(`Always-on page count: ${payload.alwaysOnPageCount}`);
+            if (payload.written) {
+              log.info("Written to core.json; lanes invalidated.");
+            } else {
+              log.info("Preview only — re-run with --yes to apply.");
             }
           },
         );
+
+      // ── rebuild-index ─────────────────────────────────────────────────────
+
+      v3.command("rebuild-index")
+        .description("Invalidate the v3 lanes so the next turn rebuilds")
+        .addHelpText(
+          "after",
+          `
+Drops the daemon's cached v3 shadow lanes so the tree + needle are rebuilt
+from the current on-disk state on the next turn. Useful after editing leaf
+files or assignments out-of-band.
+
+Examples:
+  $ assistant memory v3 rebuild-index`,
+        )
+        .action(async () => {
+          const result = await cliIpcCall<MemoryV3RebuildIndexResult>(
+            "memory_v3_rebuild_index",
+            { body: {} },
+          );
+          if (!result.ok) {
+            log.error(result.error ?? "Failed to invalidate the v3 lanes");
+            process.exitCode = 1;
+            return;
+          }
+          log.info("v3 lanes invalidated; next turn will rebuild.");
+        });
     },
   });
 }