@vellumai/assistant 0.8.6 → 0.8.7

package/src/memory/v3/traversal.ts

@@ -1,211 +0,0 @@
-/**
- * Memory v3 — Tree traversal primitives.
- *
- * The *mechanical* half of the v3 read loop: a deterministic, provider-free
- * walk over the {@link TreeIndex} DAG. The intelligence — *which* child nodes
- * to recurse into at each level — is injected via the `descend` callback so
- * this module stays pure and unit-testable without an LLM. The driver PR wires
- * `descend` to the model's descend/skip decision; here `descend` is just a
- * function `(nodeId, children) => chosen node-children`.
- *
- * `walkTree` fans out from a `start` node and any `seeds`, level by level:
- *   - At each node it resolves the ordered child refs, hands them to `descend`,
- *     and recurses into the chosen `node:` children (capped by `breadthBudget`).
- *   - The `page:` children the `descend` decision chooses to *keep* are collected
- *     into the returned `pages` set — pages are leaves, never recursed into. A
- *     page the decision does not keep is dropped, so the walk emits a curated
- *     selection rather than every page it passes.
- *   - A `visited` set keyed by canonical id (`node:<id>`) dedups shared
- *     sub-nodes (the DAG case) and terminates cycles (A ↔ B). A node is walked
- *     at most once regardless of how many parents reference it.
- *   - `maxDepth` bounds how deep the recursion goes; the start/seed level is
- *     depth 0.
- *
- * Each walked node emits one {@link TreeLevel} (the `harness/trace.ts` shape)
- * recording what was considered, descended, and skipped. `reasoning` is
- * supplied by the `descend` callback (the driver attaches the model's stated
- * reason); the mechanical walk defaults it to `""`.
- *
- * Processing is strictly level-by-level so `visited` mutations are never raced:
- * within a level the per-node `descend` calls run concurrently (`Promise.all`),
- * but the chosen children for the *next* level are only dedup'd and enqueued
- * after the whole level resolves.
- */
-
-import type { TreeLevel } from "../v2/harness/trace.js";
-import type { ChildRef, TreeIndex } from "./tree-index.js";
-
-/**
- * The decision injected into {@link walkTree}. Given a node id and its ordered
- * child refs, return the *node* children to recurse into and the *page* children
- * to keep for the answer. The driver wires this to the LLM; tests pass a
- * deterministic stub.
- *
- * Returning a `reasoning` string is optional — when present it is threaded into
- * the emitted {@link TreeLevel}; absent, the level's `reasoning` defaults to
- * `""`. Returned `descend` refs that are not `node:` children of `nodeId`, and
- * `keep` refs that are not `page:` children of `nodeId`, are ignored by the walk
- * (it only acts on the distinct children it actually offered).
- */
-export type DescendDecision = (
-  nodeId: string,
-  children: ReadonlyArray<ChildRef>,
-) => Promise<DescendResult> | DescendResult;
-
-/**
- * The result of a {@link DescendDecision}. `descend` lists the `node:` children
- * chosen for recursion; `keep` lists the `page:` children to collect into the
- * walk's result; `reasoning` is the optional model rationale recorded on the
- * level.
- */
-export interface DescendResult {
-  descend: ChildRef[];
-  keep: ChildRef[];
-  reasoning?: string;
-}
-
-/** Options controlling a {@link walkTree} run. */
-export interface WalkOptions {
-  /** Entry node id; defaults to `tree.root`. */
-  start?: string;
-  /** Extra node ids to start from in parallel with `start`. */
-  seeds?: string[];
-  /** Max `node:` children to descend into per node (after the `descend` pick). */
-  breadthBudget: number;
-  /** Max recursion depth; the start/seed level is depth 0. */
-  maxDepth: number;
-  /** Injected descend decision (the LLM hook). */
-  descend: DescendDecision;
-}
-
-/** The result of a {@link walkTree} run. */
-export interface WalkResult {
-  /** Every `page:` slug the descend decision kept across the walk, dedup'd. */
-  pages: Set<string>;
-  /** One {@link TreeLevel} per walked node, in walk order. */
-  levels: TreeLevel[];
-}
-
-/**
- * Resolve the ordered child refs for `nodeId`. Thin accessor over
- * `tree.childrenByNode`; returns an empty array for an unknown / leaf node id so
- * callers never branch on `undefined`.
- */
-export function resolveChildren(
-  tree: TreeIndex,
-  nodeId: string,
-): ReadonlyArray<ChildRef> {
-  return tree.childrenByNode.get(nodeId) ?? [];
-}
-
-/** Canonical visited-set key for a node id. */
-function nodeKey(nodeId: string): string {
-  return `node:${nodeId}`;
-}
-
-/**
- * Walk the {@link TreeIndex} DAG from `start` (default `tree.root`) plus any
- * `seeds`, driven by the injected `descend` decision. Deterministic and
- * provider-free — see the module docstring for the full contract.
- *
- * Returns the collected leaf `pages` and the per-node `levels` trace.
- */
-export async function walkTree(
-  tree: TreeIndex,
-  opts: WalkOptions,
-): Promise<WalkResult> {
-  const { breadthBudget, maxDepth, descend } = opts;
-  const start = opts.start ?? tree.root;
-
-  const pages = new Set<string>();
-  const levels: TreeLevel[] = [];
-  const visited = new Set<string>();
-
-  // Seed the frontier with `start` + `seeds`, dedup'd and marked visited up
-  // front so a node that is both the start and a seed is walked once.
-  let frontier: string[] = [];
-  for (const id of [start, ...(opts.seeds ?? [])]) {
-    const key = nodeKey(id);
-    if (visited.has(key)) continue;
-    visited.add(key);
-    frontier.push(id);
-  }
-
-  // Depth 0 is the start/seed level; stop once we'd exceed `maxDepth`.
-  for (let depth = 0; depth <= maxDepth && frontier.length > 0; depth++) {
-    // Resolve every node on this level concurrently. `visited` is not mutated
-    // here — only after the whole level settles — so the concurrency is safe.
-    const levelResults = await Promise.all(
-      frontier.map(async (nodeId) => {
-        const children = resolveChildren(tree, nodeId);
-        const result = await descend(nodeId, children);
-        return { nodeId, children, result };
-      }),
-    );
-
-    const nextFrontier: string[] = [];
-
-    for (const { nodeId, children, result } of levelResults) {
-      // Collect only the page children the decision chose to keep, filtered to
-      // the page children this node actually offered — a decision can't keep a
-      // page the node never presented.
-      const offeredPageRefs = new Set(
-        children.filter((c) => c.kind === "page").map((c) => c.ref),
-      );
-      for (const choice of result.keep) {
-        if (choice.kind === "page" && offeredPageRefs.has(choice.ref)) {
-          pages.add(choice.ref);
-        }
-      }
-
-      // The set of node children this node legitimately offered, in order. The
-      // descend pick is intersected with this so a stub returning bogus or
-      // duplicate refs can't make the walk recurse into something not offered.
-      const offeredNodes = children.filter((c) => c.kind === "node");
-      const offeredRefs = new Set(offeredNodes.map((c) => c.ref));
-
-      // Honor the descend pick in the order it was returned, dedup'd, filtered
-      // to genuinely-offered node children, skipping nodes already visited
-      // elsewhere in the DAG, and capped by `breadthBudget`. Filtering visited
-      // nodes *before* the budget check ensures the budget is spent only on
-      // nodes the walk will actually descend — an already-visited pick must not
-      // consume a slot that an unvisited sibling could use.
-      const descended: string[] = [];
-      const descendedSet = new Set<string>();
-      for (const choice of result.descend) {
-        if (choice.kind !== "node") continue;
-        if (!offeredRefs.has(choice.ref)) continue;
-        if (descendedSet.has(choice.ref)) continue;
-        if (visited.has(nodeKey(choice.ref))) continue;
-        if (descended.length >= breadthBudget) break;
-        descendedSet.add(choice.ref);
-        descended.push(choice.ref);
-      }
-
-      const considered = offeredNodes.map((c) => c.ref);
-      const skipped = considered.filter((ref) => !descendedSet.has(ref));
-
-      levels.push({
-        node: nodeId,
-        considered,
-        descended,
-        skipped,
-        reasoning: result.reasoning ?? "",
-      });
-
-      // Enqueue chosen node children for the next level. Mark visited now (the
-      // level has fully resolved) so a shared sub-node or a cycle is enqueued at
-      // most once across the whole walk.
-      for (const ref of descended) {
-        const key = nodeKey(ref);
-        if (visited.has(key)) continue;
-        visited.add(key);
-        nextFrontier.push(ref);
-      }
-    }
-
-    frontier = nextFrontier;
-  }
-
-  return { pages, levels };
-}

package/src/memory/v3/tree-index.ts

@@ -1,237 +0,0 @@
-/**
- * Memory v3 — Tree index (DAG build + cache).
- *
- * The v3 tree is a DAG *overlay* over the flat `memory/concepts/` pages: every
- * node carries an ordered `children` list whose entries are either
- * `"page:<slug>"` (a leaf concept page, canonical content untouched by v3) or
- * `"node:<id>"` (a sub-node in the tree). A page or node may be referenced by
- * more than one parent — hence DAG, not tree.
- *
- * This module scans every node on disk and materializes that edge list into
- * forward and reverse adjacency maps so downstream routing/validation can walk
- * the graph without re-reading the filesystem:
- *   - `childrenByNode` — node id → ordered child refs (forward edges).
- *   - `parentsByNode` — node id → set of parent node ids (reverse edges for
- *     `node:` children).
- *   - `pageParents` — page slug → set of parent node ids (reverse edges for
- *     `page:` children).
- *
- * The build is **structural only**: it never verifies that a referenced page
- * or node actually exists. Dangling refs are retained in the adjacency maps so
- * a later validation pass can report them. Root detection prefers the reserved
- * `_root` id; absent that it picks the single node with no parents (warning and
- * picking deterministically if the choice is ambiguous).
- *
- * The build is cached module-locally per `workspaceDir`, mirroring
- * `../v2/page-index.ts`. Callers must invalidate via `invalidateTreeIndex` when
- * tree nodes change — `tree-store.ts`'s `writeNode` / `deleteNode` already do.
- */
-
-import { getLogger } from "../../util/logger.js";
-import { listNodes, readNode, ROOT_NODE_ID } from "./tree-store.js";
-import type { TreeNode } from "./types.js";
-
-const log = getLogger("memory-v3-tree-index");
-
-/** Prefix marking a child ref that targets a leaf concept page. */
-const PAGE_REF_PREFIX = "page:";
-
-/** Prefix marking a child ref that targets a sub-node in the tree. */
-const NODE_REF_PREFIX = "node:";
-
-/**
- * A single parsed `children` entry. `kind` distinguishes a leaf concept page
- * (`"page"`) from a sub-node (`"node"`); `ref` is the bare slug or node id with
- * the `page:` / `node:` prefix stripped.
- */
-export interface ChildRef {
-  kind: "page" | "node";
-  ref: string;
-}
-
-/**
- * Snapshot of the v3 tree DAG for one workspace.
- *
- * `nodes` is every readable node keyed by id. The three adjacency maps are
- * derived from each node's `children`:
- *   - `childrenByNode` — forward edges, preserving `children` order.
- *   - `parentsByNode` — reverse edges restricted to `node:` children.
- *   - `pageParents` — reverse edges restricted to `page:` children, keyed by
- *     page slug.
- *
- * `root` is the entry-point node id (`_root` when present). Dangling refs (a
- * `node:`/`page:` target with no on-disk file) are retained throughout —
- * validation, not the index build, is responsible for surfacing them.
- */
-export interface TreeIndex {
-  nodes: Map<string, TreeNode>;
-  childrenByNode: Map<string, ReadonlyArray<ChildRef>>;
-  parentsByNode: Map<string, Set<string>>;
-  pageParents: Map<string, Set<string>>;
-  root: string;
-}
-
-interface CachedIndex {
-  workspaceDir: string;
-  index: TreeIndex;
-}
-
-let cache: CachedIndex | null = null;
-
-/**
- * Parse a raw `children` entry into a {@link ChildRef}. Returns `null` for any
- * entry that does not carry a recognized `page:` / `node:` prefix or whose ref
- * body is empty — those are malformed and dropped (with a warn) rather than
- * faithfully threaded through adjacency.
- */
-function parseChildRef(raw: string): ChildRef | null {
-  if (raw.startsWith(PAGE_REF_PREFIX)) {
-    const ref = raw.slice(PAGE_REF_PREFIX.length);
-    return ref.length > 0 ? { kind: "page", ref } : null;
-  }
-  if (raw.startsWith(NODE_REF_PREFIX)) {
-    const ref = raw.slice(NODE_REF_PREFIX.length);
-    return ref.length > 0 ? { kind: "node", ref } : null;
-  }
-  return null;
-}
-
-/** Append `parent` to the parent-set for `key`, creating the set on demand. */
-function addParent(
-  map: Map<string, Set<string>>,
-  key: string,
-  parent: string,
-): void {
-  let parents = map.get(key);
-  if (!parents) {
-    parents = new Set();
-    map.set(key, parents);
-  }
-  parents.add(parent);
-}
-
-/**
- * Pick the root node id from the materialized adjacency. Prefers the reserved
- * {@link ROOT_NODE_ID} when a node with that id exists. Otherwise the root is
- * the single node with no parents; if several nodes are parentless the choice
- * is ambiguous, so warn and pick the ASCII-smallest id for determinism. With no
- * nodes at all the root is `_root` (the well-known handle a migration authors
- * first), matching the empty-workspace contract.
- */
-function pickRoot(
-  nodes: Map<string, TreeNode>,
-  parentsByNode: Map<string, Set<string>>,
-): string {
-  if (nodes.has(ROOT_NODE_ID)) {
-    return ROOT_NODE_ID;
-  }
-
-  const parentless = [...nodes.keys()].filter(
-    (id) => !parentsByNode.has(id) || parentsByNode.get(id)!.size === 0,
-  );
-  parentless.sort();
-
-  if (parentless.length === 1) {
-    return parentless[0];
-  }
-  if (parentless.length === 0) {
-    return ROOT_NODE_ID;
-  }
-  log.warn(
-    { parentless },
-    "Ambiguous tree root — no '_root' node and multiple parentless nodes; picking ASCII-smallest deterministically",
-  );
-  return parentless[0];
-}
-
-/**
- * Return a `TreeIndex` for `workspaceDir`. Cached module-locally; the cache is
- * invalidated by `invalidateTreeIndex` (called by `tree-store.ts` hooks when
- * nodes change).
- *
- * Cold builds list every node and read them in parallel, dropping any whose
- * read rejects with a warn so one broken node never blocks the rest of the
- * index. Each readable node's `children` is parsed into {@link ChildRef}s and
- * threaded into forward (`childrenByNode`) and reverse (`parentsByNode` /
- * `pageParents`) adjacency. The build is structural only — referenced
- * pages/nodes are never verified to exist; dangling refs are retained for a
- * later validation pass.
- */
-export async function getTreeIndex(workspaceDir: string): Promise<TreeIndex> {
-  if (cache && cache.workspaceDir === workspaceDir) {
-    return cache.index;
-  }
-
-  const ids = await listNodes(workspaceDir);
-
-  // Read every node in parallel; nodes whose read rejects are dropped with a
-  // warn so a single broken node never blocks the rest of the index.
-  const settled = await Promise.allSettled(
-    ids.map((id) => readNode(workspaceDir, id)),
-  );
-
-  const nodes = new Map<string, TreeNode>();
-  const childrenByNode = new Map<string, ReadonlyArray<ChildRef>>();
-  const parentsByNode = new Map<string, Set<string>>();
-  const pageParents = new Map<string, Set<string>>();
-
-  for (let i = 0; i < settled.length; i++) {
-    const result = settled[i];
-    const id = ids[i];
-    if (result.status === "rejected") {
-      log.warn(
-        { id, err: result.reason },
-        "Dropping tree node from index — read failed",
-      );
-      continue;
-    }
-    const node = result.value;
-    // `readNode` returns null only on ENOENT; a node listed by `listNodes`
-    // that vanishes between list and read is a benign race — drop it silently.
-    if (!node) continue;
-    nodes.set(id, node);
-  }
-
-  // Build adjacency in a second pass so every node is registered first — that
-  // keeps a deterministic, list-order iteration independent of read timing.
-  for (const node of nodes.values()) {
-    const childRefs: ChildRef[] = [];
-    for (const raw of node.frontmatter.children) {
-      const parsed = parseChildRef(raw);
-      if (!parsed) {
-        log.warn(
-          { id: node.id, raw },
-          "Dropping malformed child ref — expected 'page:<slug>' or 'node:<id>'",
-        );
-        continue;
-      }
-      childRefs.push(parsed);
-      const reverse = parsed.kind === "node" ? parentsByNode : pageParents;
-      addParent(reverse, parsed.ref, node.id);
-    }
-    childrenByNode.set(node.id, childRefs);
-  }
-
-  const root = pickRoot(nodes, parentsByNode);
-
-  const index: TreeIndex = {
-    nodes,
-    childrenByNode,
-    parentsByNode,
-    pageParents,
-    root,
-  };
-  cache = { workspaceDir, index };
-  return index;
-}
-
-/**
- * Clear the cached index. Pass `workspaceDir` to scope invalidation to a
- * specific cache entry; omit it to clear unconditionally.
- */
-export function invalidateTreeIndex(workspaceDir?: string): void {
-  if (!cache) return;
-  if (workspaceDir === undefined || cache.workspaceDir === workspaceDir) {
-    cache = null;
-  }
-}