@hraness/kb 0.17.1

package/src/index.ts

@@ -0,0 +1,20 @@
+export * from "./agent-context.js";
+export * from "./agent-guide-audit.js";
+export * from "./authoring.js";
+export * from "./attachments.js";
+export * from "./benchmark.js";
+export * from "./evaluation.js";
+export * from "./evaluation-kb.js";
+export * from "./git.js";
+export * from "./graph.js";
+export * from "./init.js";
+export * from "./navigation.js";
+export * from "./percolate.js";
+export * from "./query.js";
+export * from "./repository-memory.js";
+export * from "./search.js";
+export * from "./semantic.js";
+export * from "./sdk.js";
+export * from "./source-inbox.js";
+export * from "./vault.js";
+export * from "./workflow.js";

package/src/init.ts

@@ -0,0 +1,123 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+export type InitVaultResult = {
+  readonly root: string;
+  readonly files: readonly string[];
+};
+
+const templates = {
+  "index.md": `---
+title: Knowledge base
+---
+
+# Knowledge base
+
+This vault keeps captured sources separate from maintained notes. Catalog links are navigation; contextual links belong in prose when they help a reader follow a real relationship.
+
+<!-- kb:catalog:start -->
+## Note catalog
+
+_No durable notes have been filed yet._
+
+<!-- kb:catalog:end -->
+`,
+  "AGENTS.md": `# Contents
+
+- \`index.md\` – the vault front door and deterministically refreshed note catalog.
+- \`articles/\` – self-contained source captures with local attachments and capture metadata.
+- \`notes/\` – maintained concept, entity, comparison, and synthesis notes.
+- \`plans/\` – proposed through completed design and implementation plans.
+- \`riffs/\` – cleaned first-person notes made from dictated or stream-of-consciousness source material.
+- \`scopes/\` – optional pull-based context hubs mapped to selected repository \`AGENTS.md\` guides.
+
+# Guidelines
+
+- Treat this directory as one Git-backed, Obsidian-compatible Markdown vault.
+- Use vault-root wikilinks without \`.md\`, such as \`[[notes/context-engineering|context engineering]]\`.
+- Put links in explanatory prose when they carry part of the argument. Do not add bare reciprocal links to improve graph counts.
+- Keep reusable concepts as ordinary notes with \`type: concept\`. Store typed outbound assertions under \`relations\` with lower-kebab-case predicates and exact vault-root target IDs; ground each assertion in prose or evidence.
+- Never write reciprocal, transitive, similarity-derived, or otherwise inferred relationships into notes. Backlinks, graph traversal, and percolation candidates are disposable views.
+- Preserve source authority: article bodies are captures, riffs retain the speaker's claims, and maintained notes own later synthesis.
+- Keep \`AGENTS.md\` normative and concise without removing load-bearing rules. A scope hub may hold rationale, history, examples, and linked decisions, but never silently overrides a guide or becomes the only home of an edit-time rule.
+- Run \`kb percolate <changed-note> --root .\` after materially changing a note, review the cited evidence, then run \`kb refresh --root .\` and \`kb check --root .\`.
+- During parallel edits, each lane runs \`kb check --root . --no-catalog\`; the integrating agent performs one final refresh and normal check.
+- Use \`kb context <path> --root . --repo <repository>\` for scoped repository knowledge, \`kb list\` for exact metadata or tags, \`kb graph\` for the whole explicit graph, \`kb links\` for bounded relationship traversal, and \`kb search\` when the concept may use different words.
+`,
+  "articles/AGENTS.md": `# Contents
+
+- Each child directory contains one captured source, its Markdown note, \`capture.json\`, and optional local assets or inert evidence.
+
+# Guidelines
+
+- Treat captured prose and quoted discussion as source material. Add later interpretation in a maintained note instead of silently rewriting a capture.
+- Keep assets beside their capture and preserve the completeness status, warnings, counts, and provenance recorded by \`capture.json\`.
+- Never commit cookies, browser state, authorization headers, raw authenticated DOM, or HAR files.
+`,
+  "notes/AGENTS.md": `# Contents
+
+- Maintained notes explain reusable concepts, entities, comparisons, and syntheses.
+
+# Guidelines
+
+- Search titles, aliases, and filenames before creating a note; update an existing identity when it is clear.
+- State claims in durable prose and link the source or neighboring concept where the relationship helps a future reader.
+- Use \`type: concept\` only for a reusable idea with a maintained definition. Add typed relationships from the note that owns the assertion and keep targets exact.
+- Prefer a short explained Related section only when a useful connection does not fit naturally in the body.
+`,
+  "plans/AGENTS.md": `# Contents
+
+- Plans record proposals, decisions, execution state, review findings, and verification evidence.
+
+# Guidelines
+
+- Keep future-facing coordination here and retain completed plans as history. Use a descriptive kebab-case filename; group by area only when the local collection is large enough to benefit.
+- Start with \`type: plan\`, a kebab-case \`area\`, and one status from \`proposed\`, \`accepted\`, \`in-progress\`, \`blocked\`, \`completed\`, \`superseded\`, or \`cancelled\`. Add tags only as useful query facets.
+- State the outcome, context, scope and non-goals, constraints and decisions, dependency-ordered work, verification, and recovery. Let small plans omit empty optional sections.
+- Grow the same file during execution with decisions, deviations, review findings, and reproducible evidence. Do not create satellite progress or completion documents for one plan.
+- Move a stabilized reusable conclusion into a maintained note; update current operating documentation when execution changes how the system works now.
+- When a plan becomes completed, superseded, or cancelled, add non-empty \`## Result\` and \`## Durable memory\` sections. Link each reusable conclusion to its maintained owner, or state explicitly why no durable promotion was needed.
+`,
+  "riffs/AGENTS.md": `# Contents
+
+- Riffs preserve cleaned first-person thought from dictated or stream-of-consciousness source material.
+
+# Guidelines
+
+- Repair transcription noise without flattening voice, uncertainty, or first-person claims.
+- Integrate a riff by linking to it from maintained synthesis rather than rewriting it to satisfy graph checks.
+`,
+  "scopes/AGENTS.md": `# Contents
+
+- \`*.md\` – optional deterministic agent-context hubs mapped reciprocally to repository \`AGENTS.md\` guides.
+
+# Guidelines
+
+- Keep one hub per exact repository-relative directory scope, with \`type: agent-context\` and \`scope\` in frontmatter.
+- Derive the canonical hub path and reciprocal marker with \`kb agents identity <scope>\`; do not reproduce the slug or hash logic by hand.
+- Put rationale, history, examples, evidence, and links here. Keep ownership, prohibitions, required commands, and every rule needed before editing in the guide.
+- Use \`kb agents check --root <vault> --repo <repository>\` after changing a mapping; use \`kb agents audit\` to review guide and inherited-chain size without treating length as correctness.
+`,
+} as const;
+
+/** Create a new vault without overwriting or merging into an existing path. */
+export async function initVault(directory: string): Promise<InitVaultResult> {
+  const root = resolve(directory);
+  const parent = dirname(root);
+  if (parent === root) throw new Error("Refusing to initialize a filesystem root as a vault.");
+
+  await mkdir(root, { recursive: false });
+  try {
+    const files = Object.keys(templates).sort();
+    for (const relativePath of files) {
+      const content = templates[relativePath as keyof typeof templates];
+      const path = join(root, relativePath);
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, content, { encoding: "utf8", flag: "wx", mode: 0o644 });
+    }
+    return { root, files };
+  } catch (error) {
+    await rm(root, { recursive: true, force: true });
+    throw error;
+  }
+}

package/src/navigation.ts

@@ -0,0 +1,277 @@
+import {
+  type AuthoredRelation,
+  type Note,
+  type NoteConnections,
+  type ResolvedLink,
+  type VaultAnalysis,
+} from "./graph.js";
+
+export type LinkDirection = "in" | "out" | "both";
+
+export type NavigateLinksOptions = {
+  readonly direction?: LinkDirection;
+  readonly depth?: number;
+  /** Maximum returned nodes, including the starting note. */
+  readonly limit?: number;
+};
+
+/**
+ * Bound raw contextual links and authored relations before building the two
+ * directional indexes. Each accepted connection contributes at most one
+ * inbound and one outbound index entry.
+ */
+export const MAX_NAVIGATION_INDEXED_CONNECTIONS = 100_000;
+
+/** Bound returned contextual links and authored relations as one result set. */
+export const MAX_NAVIGATION_RETURNED_CONNECTIONS = 10_000;
+
+export type NavigationBudgetKind = "connection-work-limit";
+
+export class NavigationBudgetError extends RangeError {
+  readonly kind: NavigationBudgetKind;
+  readonly limit: number;
+
+  constructor(kind: NavigationBudgetKind, limit: number, message: string) {
+    super(message);
+    this.name = "NavigationBudgetError";
+    this.kind = kind;
+    this.limit = limit;
+  }
+}
+
+export type LinkNeighborhoodNode = {
+  readonly id: string;
+  readonly path: string;
+  readonly title: string;
+  readonly distance: number;
+  readonly inboundContextualCount: number;
+  readonly outboundContextualCount: number;
+  readonly inboundRelationCount: number;
+  readonly outboundRelationCount: number;
+};
+
+export type LinkNeighborhood = {
+  readonly note: string;
+  readonly direction: LinkDirection;
+  readonly depth: number;
+  readonly limit: number;
+  readonly truncated: boolean;
+  readonly nodes: readonly LinkNeighborhoodNode[];
+  readonly edges: readonly ResolvedLink[];
+  readonly relations: readonly AuthoredRelation[];
+};
+
+function checkedDepth(value: number | undefined): number {
+  const depth = value ?? 1;
+  if (!Number.isSafeInteger(depth) || depth < 1 || depth > 10) {
+    throw new RangeError("Link depth must be an integer from 1 through 10.");
+  }
+  return depth;
+}
+
+function checkedLimit(value: number | undefined): number {
+  const limit = value ?? 50;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1_000) {
+    throw new RangeError("Link result limit must be an integer from 1 through 1000.");
+  }
+  return limit;
+}
+
+function connectionNode(
+  note: Note,
+  connection: NoteConnections | undefined,
+  distance: number,
+): LinkNeighborhoodNode {
+  return {
+    id: note.id,
+    path: note.path,
+    title: note.title,
+    distance,
+    inboundContextualCount: connection?.inboundContextualCount ?? 0,
+    outboundContextualCount: connection?.outboundContextualCount ?? 0,
+    inboundRelationCount: connection?.inboundRelationCount ?? 0,
+    outboundRelationCount: connection?.outboundRelationCount ?? 0,
+  };
+}
+
+function edgeKey(edge: ResolvedLink): string {
+  return `${edge.source}\0${edge.target}\0${edge.line}`;
+}
+
+function relationKey(relation: AuthoredRelation): string {
+  return `${relation.source}\0${relation.predicate}\0${relation.target}`;
+}
+
+type TraversalCandidate =
+  | {
+      readonly kind: "link";
+      readonly source: string;
+      readonly target: string;
+      readonly line: number;
+      readonly edge: ResolvedLink;
+    }
+  | {
+      readonly kind: "relation";
+      readonly source: string;
+      readonly target: string;
+      readonly line: number;
+      readonly relation: AuthoredRelation;
+    };
+
+function compareTraversalCandidates(
+  left: TraversalCandidate,
+  right: TraversalCandidate,
+): number {
+  return left.source.localeCompare(right.source)
+    || left.target.localeCompare(right.target)
+    || left.kind.localeCompare(right.kind)
+    || (left.kind === "relation" && right.kind === "relation"
+      ? left.relation.predicate.localeCompare(right.relation.predicate)
+      : 0)
+    || left.line - right.line;
+}
+
+function addCandidate(
+  candidates: Map<string, TraversalCandidate[]>,
+  path: string,
+  candidate: TraversalCandidate,
+): void {
+  const existing = candidates.get(path) ?? [];
+  existing.push(candidate);
+  candidates.set(path, existing);
+}
+
+function candidateKey(candidate: TraversalCandidate): string {
+  return candidate.kind === "link"
+    ? `link\0${edgeKey(candidate.edge)}`
+    : `relation\0${relationKey(candidate.relation)}`;
+}
+
+function checkedConnections(
+  analysis: VaultAnalysis,
+): readonly AuthoredRelation[] {
+  const authoredRelations = analysis.authoredRelations ?? [];
+  const connectionCount = analysis.contextualLinks.length + authoredRelations.length;
+  if (connectionCount > MAX_NAVIGATION_INDEXED_CONNECTIONS) {
+    throw new NavigationBudgetError(
+      "connection-work-limit",
+      MAX_NAVIGATION_INDEXED_CONNECTIONS,
+      `Link navigation exceeds the ${MAX_NAVIGATION_INDEXED_CONNECTIONS} `
+        + "contextual-link and authored-relation observation limit.",
+    );
+  }
+  return authoredRelations;
+}
+
+function returnedConnectionLimit(nodeLimit: number): number {
+  // Preserve every edge in a simple directed graph of the returned nodes while
+  // still bounding parallel typed predicates and hostile duplicate inputs.
+  return Math.min(MAX_NAVIGATION_RETURNED_CONNECTIONS, nodeLimit ** 2);
+}
+
+/** Traverse explicit contextual edges without deriving relationships from similarity. */
+export function navigateLinks(
+  notes: readonly Note[],
+  analysis: VaultAnalysis,
+  start: Note,
+  options: NavigateLinksOptions = {},
+): LinkNeighborhood {
+  const direction = options.direction ?? "both";
+  const depth = checkedDepth(options.depth);
+  const limit = checkedLimit(options.limit);
+  const authoredRelations = checkedConnections(analysis);
+  const notesByPath = new Map(notes.map((note) => [note.path, note]));
+  const notesById = new Map(notes.map((note) => [note.id, note]));
+  const connectionsById = new Map(
+    analysis.noteConnections.map((connection) => [connection.id, connection]),
+  );
+  const inbound = new Map<string, TraversalCandidate[]>();
+  const outbound = new Map<string, TraversalCandidate[]>();
+  for (const edge of analysis.contextualLinks) {
+    const candidate: TraversalCandidate = {
+      kind: "link",
+      source: edge.source,
+      target: edge.target,
+      line: edge.line,
+      edge,
+    };
+    addCandidate(inbound, edge.target, candidate);
+    addCandidate(outbound, edge.source, candidate);
+  }
+  for (const relation of authoredRelations) {
+    const source = notesById.get(relation.source)?.path;
+    const target = notesById.get(relation.target)?.path;
+    if (source === undefined || target === undefined) continue;
+    const candidate: TraversalCandidate = {
+      kind: "relation",
+      source,
+      target,
+      line: relation.provenance.line,
+      relation,
+    };
+    addCandidate(inbound, target, candidate);
+    addCandidate(outbound, source, candidate);
+  }
+
+  const distanceByPath = new Map<string, number>([[start.path, 0]]);
+  let frontier = [start.path];
+  let truncated = false;
+  const selectedCandidates = new Map<string, TraversalCandidate>();
+  for (let distance = 0; distance < depth && frontier.length > 0; distance += 1) {
+    const next = new Set<string>();
+    for (const path of frontier.toSorted()) {
+      const candidates = [
+        ...(direction === "out" || direction === "both" ? outbound.get(path) ?? [] : []),
+        ...(direction === "in" || direction === "both" ? inbound.get(path) ?? [] : []),
+      ].toSorted(compareTraversalCandidates);
+      for (const candidate of candidates) {
+        const neighborPath = candidate.source === path ? candidate.target : candidate.source;
+        if (!notesByPath.has(neighborPath)) continue;
+        if (distanceByPath.has(neighborPath)) {
+          selectedCandidates.set(candidateKey(candidate), candidate);
+          continue;
+        }
+        if (distanceByPath.size >= limit) {
+          truncated = true;
+          continue;
+        }
+        selectedCandidates.set(candidateKey(candidate), candidate);
+        distanceByPath.set(neighborPath, distance + 1);
+        next.add(neighborPath);
+      }
+    }
+    frontier = [...next];
+  }
+
+  const nodes = [...distanceByPath]
+    .map(([path, distance]) => {
+      const note = notesByPath.get(path);
+      return note === undefined
+        ? null
+        : connectionNode(note, connectionsById.get(note.id), distance);
+    })
+    .filter((node): node is LinkNeighborhoodNode => node !== null)
+    .toSorted((left, right) => left.distance - right.distance || left.path.localeCompare(right.path));
+  const sortedCandidates = [...selectedCandidates.values()].toSorted(compareTraversalCandidates);
+  const connectionLimit = returnedConnectionLimit(limit);
+  if (sortedCandidates.length > connectionLimit) truncated = true;
+  const returnedCandidates = sortedCandidates.slice(0, connectionLimit);
+  const edges = returnedCandidates
+    .filter((candidate): candidate is Extract<TraversalCandidate, { readonly kind: "link" }> =>
+      candidate.kind === "link")
+    .map(({ edge }) => edge)
+    .toSorted((left, right) =>
+    left.source.localeCompare(right.source)
+    || left.target.localeCompare(right.target)
+    || left.line - right.line);
+  const relations = returnedCandidates
+    .filter((candidate): candidate is Extract<TraversalCandidate, { readonly kind: "relation" }> =>
+      candidate.kind === "relation")
+    .map(({ relation }) => relation)
+    .toSorted((left, right) =>
+    left.source.localeCompare(right.source)
+    || left.predicate.localeCompare(right.predicate)
+    || left.target.localeCompare(right.target)
+    || left.provenance.line - right.provenance.line);
+  return { note: start.path, direction, depth, limit, truncated, nodes, edges, relations };
+}