@thecat69/cache-ctrl 1.0.0 → 1.1.1

package/src/files/gitFiles.ts

@@ -10,6 +10,11 @@ function parseGitOutput(stdout: string): string[] {
     .filter((l) => l.length > 0);
 }
 
+/**
+ * Returns git-tracked file paths for a repository.
+ *
+ * Falls back to `[]` when git is unavailable, command execution fails, or directory is not a git repo.
+ */
 export async function getGitTrackedFiles(repoRoot: string): Promise<string[]> {
   try {
     const result = await execFileAsync("git", ["ls-files"], { cwd: repoRoot, maxBuffer: 10 * 1024 * 1024 });
@@ -19,6 +24,11 @@ export async function getGitTrackedFiles(repoRoot: string): Promise<string[]> {
   }
 }
 
+/**
+ * Returns git-tracked files deleted from the working tree.
+ *
+ * Falls back to `[]` when git is unavailable, command execution fails, or directory is not a git repo.
+ */
 export async function getGitDeletedFiles(repoRoot: string): Promise<string[]> {
   try {
     const result = await execFileAsync("git", ["ls-files", "--deleted"], { cwd: repoRoot, maxBuffer: 10 * 1024 * 1024 });
@@ -28,6 +38,11 @@ export async function getGitDeletedFiles(repoRoot: string): Promise<string[]> {
   }
 }
 
+/**
+ * Returns untracked files that are not ignored by git.
+ *
+ * Falls back to `[]` when git is unavailable, command execution fails, or directory is not a git repo.
+ */
 export async function getUntrackedNonIgnoredFiles(repoRoot: string): Promise<string[]> {
   try {
     const result = await execFileAsync("git", ["ls-files", "--others", "--exclude-standard"], {

package/src/files/openCodeInstaller.ts

@@ -4,9 +4,18 @@ import path from "node:path";
 
 import type { InstallResult } from "../types/commands.js";
 import { ErrorCode, type Result } from "../types/result.js";
+import { toUnknownResult } from "../utils/errors.js";
 
 const SKILL_NAMES = ["cache-ctrl-external", "cache-ctrl-local", "cache-ctrl-caller"] as const;
 
+/**
+ * Resolves the OpenCode configuration directory.
+ *
+ * @param overrideDir - Explicit CLI override path.
+ * @returns Absolute config directory path used for tool and skill installation.
+ * @remarks Resolution order: explicit override → `%APPDATA%/opencode` on Windows →
+ * `$XDG_CONFIG_HOME/opencode` on Unix-like systems → `~/.config/opencode` fallback.
+ */
 export function resolveOpenCodeConfigDir(overrideDir?: string): string {
   if (overrideDir !== undefined) {
     return overrideDir;
@@ -21,6 +30,7 @@ export function resolveOpenCodeConfigDir(overrideDir?: string): string {
   return path.join(xdgConfigHome, "opencode");
 }
 
+/** Builds the generated OpenCode tool wrapper file content. */
 export function buildToolWrapperContent(packageRoot: string): string {
   const normalizedPackageRoot = packageRoot.replace(/\\/g, "/");
 
@@ -31,6 +41,15 @@ export function buildToolWrapperContent(packageRoot: string): string {
   ].join("\n");
 }
 
+/**
+ * Installs or refreshes OpenCode tool + skill integration files.
+ *
+ * @param configDir - Target OpenCode config directory.
+ * @param packageRoot - Installed package root used to resolve bundled assets.
+ * @returns Written tool path and copied skill file paths.
+ * @remarks Operation is idempotent: reruns overwrite the wrapper and recopy skill files
+ * to align the config directory with the currently installed package version.
+ */
 export async function installOpenCodeIntegration(configDir: string, packageRoot: string): Promise<Result<InstallResult>> {
   try {
     const toolDir = path.join(configDir, "tools");
@@ -60,7 +79,7 @@ export async function installOpenCodeIntegration(configDir: string, packageRoot:
       },
     };
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { ok: false, error: message, code: ErrorCode.FILE_WRITE_ERROR };
+    const unknownError = toUnknownResult(err);
+    return { ...unknownError, code: ErrorCode.FILE_WRITE_ERROR };
   }
 }

package/src/http/freshnessChecker.ts

@@ -1,9 +1,16 @@
+/** Input payload for one HTTP freshness check request. */
 export interface FreshnessCheckInput {
   url: string;
   etag?: string;
   last_modified?: string;
 }
 
+/**
+ * Output payload for one HTTP freshness check request.
+ *
+ * @remarks Status semantics: HTTP 304 maps to `fresh`, HTTP 200 maps to `stale`, and
+ * all other outcomes (network errors, blocked URLs, non-200/304 responses) map to `error`.
+ */
 export interface FreshnessCheckOutput {
   url: string;
   status: "fresh" | "stale" | "error";
@@ -30,8 +37,15 @@ export interface FreshnessCheckOutput {
  *   - ::ffff:        IPv4-mapped IPv6
  */
 const PRIVATE_IP_PATTERN =
-  /^(127\.|localhost$|10\.|169\.254\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|0\.0\.0\.0$|\[::1\]$|::1$|::ffff:|f[cd][0-9a-f]{0,2}:|\[f[cd][0-9a-f]{0,2}:)/i;
+  /^(127\.|localhost$|10\.|169\.254\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|0\.0\.0\.0$|\[::1\]$|::1$|::ffff:|\[::ffff:|f[cd][0-9a-f]{0,2}:|\[f[cd][0-9a-f]{0,2}:)/i;
 
+/**
+ * Validates whether a URL is eligible for outbound freshness checks.
+ *
+ * @remarks Security control for SSRF risk reduction. Blocks non-HTTP(S) schemes and host
+ * patterns that target loopback/private address space or raw IP-style local endpoints
+ * (for example localhost, RFC1918 IPv4 ranges, loopback/link-local, and mapped/ULA IPv6).
+ */
 export function isAllowedUrl(url: string): { allowed: boolean; reason?: string } {
   try {
     const parsed = new URL(url);
@@ -47,6 +61,14 @@ export function isAllowedUrl(url: string): { allowed: boolean; reason?: string }
   }
 }
 
+/**
+ * Performs a conditional HTTP HEAD freshness check.
+ *
+ * @param input - URL plus optional stored validators (`etag`, `last_modified`).
+ * @returns Freshness verdict and response metadata for one URL.
+ * @remarks Uses a 10-second abort timeout, sends conditional headers when available,
+ * maps 304→fresh and 200→stale, and reports all other outcomes as `error`.
+ */
 export async function checkFreshness(input: FreshnessCheckInput): Promise<FreshnessCheckOutput> {
   const allowCheck = isAllowedUrl(input.url);
   if (!allowCheck.allowed) {

package/src/index.ts

@@ -8,9 +8,15 @@ import { pruneCommand } from "./commands/prune.js";
 import { checkFreshnessCommand } from "./commands/checkFreshness.js";
 import { checkFilesCommand } from "./commands/checkFiles.js";
 import { searchCommand } from "./commands/search.js";
-import { writeCommand } from "./commands/write.js";
+import { writeLocalCommand } from "./commands/writeLocal.js";
+import { writeExternalCommand } from "./commands/writeExternal.js";
 import { installCommand } from "./commands/install.js";
+import { graphCommand } from "./commands/graph.js";
+import { mapCommand } from "./commands/map.js";
+import { watchCommand } from "./commands/watch.js";
+import { versionCommand } from "./commands/version.js";
 import { ErrorCode } from "./types/result.js";
+import { toUnknownResult } from "./utils/errors.js";
 
 type CommandName =
   | "list"
@@ -22,8 +28,13 @@ type CommandName =
   | "check-freshness"
   | "check-files"
   | "search"
-  | "write"
-  | "install";
+  | "write-local"
+  | "write-external"
+  | "install"
+  | "graph"
+  | "map"
+  | "watch"
+  | "version";
 
 function isKnownCommand(cmd: string): cmd is CommandName {
   return Object.hasOwn(COMMAND_HELP as Record<string, unknown>, cmd);
@@ -152,13 +163,25 @@ const COMMAND_HELP: Record<CommandName, CommandHelp> = {
       "  Output: Ranked list of matching cache entries.",
     ].join("\n"),
   },
-  write: {
-    usage: "write <agent> [subject] --data '<json>'",
-    description: "Write a validated cache entry from JSON",
+  "write-local": {
+    usage: "write-local --data '<json>'",
+    description: "Write a validated local cache entry",
     details: [
       "  Arguments:",
-      "    <agent>     Agent type: external or local",
-      "    [subject]   Optional subject identifier (required for external agent)",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --data '<json>'   JSON string containing the cache entry payload",
+      "",
+      "  Output: Confirmation with the written entry's key.",
+    ].join("\n"),
+  },
+  "write-external": {
+    usage: "write-external <subject> --data '<json>'",
+    description: "Write a validated external cache entry",
+    details: [
+      "  Arguments:",
+      "    <subject>   Subject identifier for the external entry",
       "",
       "  Options:",
       "    --data '<json>'   JSON string containing the cache entry payload",
@@ -179,6 +202,58 @@ const COMMAND_HELP: Record<CommandName, CommandHelp> = {
       "  Output: JSON object describing installed tool/skill paths.",
     ].join("\n"),
   },
+  graph: {
+    usage: "graph [--max-tokens <number>] [--seed <path>[,<path>...]]",
+    description: "Return a PageRank-ranked dependency graph under a token budget",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --max-tokens <number>        Token budget for ranked_files output (default: 1024)",
+      "    --seed <path>[,<path>...]    Personalize rank toward specific file path(s)",
+      "                                 (repeat --seed to provide multiple values)",
+      "",
+      "  Output: Ranked files with deps, defs, and ref_count from graph.json.",
+    ].join("\n"),
+  },
+  map: {
+    usage: "map [--depth overview|modules|full] [--folder <path-prefix>]",
+    description: "Return a semantic map of local context.json",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --depth overview|modules|full   Output depth (default: overview)",
+      "    --folder <path-prefix>          Restrict map to files whose path starts with prefix",
+      "",
+      "  Output: JSON object with global_facts, files, optional modules, and total_files.",
+    ].join("\n"),
+  },
+  watch: {
+    usage: "watch [--verbose]",
+    description: "Watch for file changes and recompute the dependency graph",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Options:",
+      "    --verbose   Log watcher lifecycle and rebuild events",
+      "",
+      "  Output: Long-running daemon process that updates graph.json on source changes.",
+    ].join("\n"),
+  },
+  version: {
+    usage: "version",
+    description: "Show the current cache-ctrl package version",
+    details: [
+      "  Arguments:",
+      "    (none)",
+      "",
+      "  Output: JSON object containing the current package version.",
+    ].join("\n"),
+  },
 };
 
 const GLOBAL_OPTIONS_SECTION = [
@@ -206,7 +281,7 @@ export function printHelp(command?: string): boolean {
       ...Object.values(COMMAND_HELP).map((h) => h.usage.length),
     );
 
-    for (const [, help] of Object.entries(COMMAND_HELP) as [CommandName, CommandHelp][]) {
+    for (const help of Object.values(COMMAND_HELP)) {
       const paddedUsage = help.usage.padEnd(maxUsageLen);
       lines.push(`  ${paddedUsage}   ${help.description}`);
     }
@@ -216,12 +291,12 @@ export function printHelp(command?: string): boolean {
     return true;
   }
 
-  const sanitized = command.replace(/[\x00-\x1F\x7F]/g, "");
-
   if (command === "help") {
     return printHelp();
   }
 
+  const sanitized = command.replace(/[\x00-\x1F\x7F]/g, "");
+
   if (!isKnownCommand(command)) {
     process.stderr.write(`Unknown command: "${sanitized}". Run 'cache-ctrl help' for available commands.\n`);
     return false;
@@ -257,6 +332,12 @@ function printError(error: { ok: false; error: string; code: string }, pretty: b
   }
 }
 
+/**
+ * Prints a structured usage error and terminates the process.
+ *
+ * @param message - Human-readable usage failure detail.
+ * @remarks Always exits with process code `2` to distinguish usage failures from runtime errors.
+ */
 function usageError(message: string): never {
   process.stderr.write(JSON.stringify({ ok: false, error: message, code: ErrorCode.INVALID_ARGS }) + "\n");
   process.exit(2);
@@ -265,8 +346,45 @@ function usageError(message: string): never {
 export { usageError };
 
 /** Flags that consume the following token as their value. Boolean flags must NOT appear here. */
-const VALUE_FLAGS = new Set(["data", "agent", "url", "max-age", "filter", "folder", "search-facts", "config-dir"]);
+const VALUE_FLAGS = new Set([
+  "data",
+  "agent",
+  "url",
+  "max-age",
+  "filter",
+  "folder",
+  "search-facts",
+  "config-dir",
+  "max-tokens",
+  "seed",
+  "depth",
+]);
+
+function collectFlagValues(argv: string[], flagName: string): string[] {
+  const values: string[] = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] !== `--${flagName}`) {
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next !== undefined) {
+      values.push(next);
+      i += 1;
+    }
+  }
+
+  return values;
+}
 
+/**
+ * Parses raw CLI argv tokens into positional args and flag key/value pairs.
+ *
+ * @param argv - Raw argument tokens (typically `process.argv.slice(2)`).
+ * @returns Parsed positional args and normalized flags map.
+ * @remarks Flags listed in `VALUE_FLAGS` consume the following token as their value;
+ * all other `--flag` tokens are treated as boolean flags.
+ */
 export function parseArgs(argv: string[]): { args: string[]; flags: Record<string, string | boolean> } {
   const positional: string[] = [];
   const flags: Record<string, string | boolean> = {};
@@ -305,7 +423,7 @@ async function main(): Promise<void> {
 
   const command = args[0];
   if (!command) {
-    usageError("Usage: cache-ctrl <command> [args]. Commands: list, inspect, flush, invalidate, touch, prune, check-freshness, check-files, search, write, install");
+    usageError("Usage: cache-ctrl <command> [args]. Commands: list, inspect, flush, invalidate, touch, prune, check-freshness, check-files, search, write-local, write-external, install, graph, map, watch, version");
   }
 
   switch (command) {
@@ -498,28 +616,54 @@ async function main(): Promise<void> {
       break;
     }
 
-    case "write": {
-      const agent = args[1];
-      if (!agent) {
-        usageError("Usage: cache-ctrl write <agent> [subject] --data '<json>'");
+    case "write-local": {
+      const dataStr = typeof flags.data === "string" ? flags.data : undefined;
+      if (!dataStr) {
+        usageError("Usage: cache-ctrl write-local --data '<json>'");
       }
-      if (agent !== "external" && agent !== "local") {
-        usageError(`Invalid agent: "${agent}". Must be external or local`);
+      let content: Record<string, unknown>;
+      try {
+        content = JSON.parse(dataStr) as Record<string, unknown>; // JSON.parse returns any; writeLocalCommand validates the payload shape via Zod before use.
+      } catch {
+        usageError("--data must be valid JSON");
+      }
+      if (typeof content !== "object" || content === null || Array.isArray(content)) {
+        usageError("--data must be a JSON object");
+      }
+      const result = await writeLocalCommand({
+        agent: "local",
+        content,
+      });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "write-external": {
+      const subject = args[1];
+      if (!subject) {
+        usageError("Usage: cache-ctrl write-external <subject> --data '<json>'");
       }
       const dataStr = typeof flags.data === "string" ? flags.data : undefined;
       if (!dataStr) {
-        usageError("Usage: cache-ctrl write <agent> [subject] --data '<json>'");
+        usageError("Usage: cache-ctrl write-external <subject> --data '<json>'");
       }
       let content: Record<string, unknown>;
       try {
-        content = JSON.parse(dataStr) as Record<string, unknown>;
+        content = JSON.parse(dataStr) as Record<string, unknown>; // JSON.parse returns any; writeExternalCommand validates the payload shape via Zod before use.
       } catch {
         usageError("--data must be valid JSON");
       }
-      const subject = agent === "external" ? args[2] : undefined;
-      const result = await writeCommand({
-        agent,
-        ...(subject !== undefined ? { subject } : {}),
+      if (typeof content !== "object" || content === null || Array.isArray(content)) {
+        usageError("--data must be a JSON object");
+      }
+      const result = await writeExternalCommand({
+        agent: "external",
+        subject,
         content,
       });
       if (result.ok) {
@@ -543,15 +687,96 @@ async function main(): Promise<void> {
       break;
     }
 
+    case "graph": {
+      if (flags["max-tokens"] === true) {
+        usageError("--max-tokens requires a numeric value");
+      }
+      const maxTokensRaw = typeof flags["max-tokens"] === "string" ? flags["max-tokens"] : undefined;
+      let maxTokensParsed: number | undefined;
+      if (maxTokensRaw !== undefined) {
+        const parsed = Number(maxTokensRaw);
+        if (!Number.isFinite(parsed) || parsed < 0) {
+          usageError(`Invalid --max-tokens value: "${maxTokensRaw}". Must be a non-negative number`);
+        }
+        maxTokensParsed = parsed;
+      }
+      if (flags.seed === true) {
+        usageError("--seed requires a value: --seed <path>[,<path>...]");
+      }
+      const seedFlagValues = collectFlagValues(rawArgs, "seed");
+      const seed = seedFlagValues
+        .flatMap((value) => value.split(","))
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0);
+
+      const result = await graphCommand({
+        ...(maxTokensParsed !== undefined ? { maxTokens: maxTokensParsed } : {}),
+        ...(seed.length > 0 ? { seed } : {}),
+      });
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "map": {
+      if (flags.depth === true) {
+        usageError("--depth requires a value: --depth overview|modules|full");
+      }
+      const depthRaw = typeof flags.depth === "string" ? flags.depth : undefined;
+      if (depthRaw !== undefined && depthRaw !== "overview" && depthRaw !== "modules" && depthRaw !== "full") {
+        usageError(`Invalid --depth value: "${depthRaw}". Must be overview, modules, or full`);
+      }
+      if (flags.folder === true) {
+        usageError("--folder requires a value: --folder <path-prefix>");
+      }
+      const folder = typeof flags.folder === "string" ? flags.folder : undefined;
+
+      const result = await mapCommand({
+        ...(depthRaw !== undefined ? { depth: depthRaw } : {}),
+        ...(folder !== undefined ? { folder } : {}),
+      });
+
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "watch": {
+      const result = await watchCommand({ verbose: flags.verbose === true });
+      if (!result.ok) {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "version": {
+      const result = versionCommand({});
+      if (result.ok) {
+        printResult(result, pretty);
+      } else {
+        printError(result, pretty);
+        process.exit(1);
+      }
+      break;
+    }
+
     default:
-      usageError(`Unknown command: "${command}". Commands: list, inspect, flush, invalidate, touch, prune, check-freshness, check-files, search, write, install`);
+      usageError(`Unknown command: "${command}". Commands: list, inspect, flush, invalidate, touch, prune, check-freshness, check-files, search, write-local, write-external, install, graph, map, watch, version`);
   }
 }
 
 if (import.meta.main) {
   main().catch((err: unknown) => {
-    const error = err as Error;
-    process.stderr.write(JSON.stringify({ ok: false, error: error.message, code: ErrorCode.UNKNOWN }) + "\n");
+    process.stderr.write(JSON.stringify(toUnknownResult(err)) + "\n");
     process.exit(1);
   });
 }

package/src/search/keywordSearch.ts

@@ -1,6 +1,15 @@
 import type { CacheEntry } from "../types/cache.js";
 import { getFileStem } from "../utils/fileStem.js";
 
+/**
+ * Scores a cache entry against one or more keywords.
+ *
+ * @param entry - Candidate cache entry.
+ * @param keywords - Search keywords.
+ * @returns Numeric relevance score (higher is better).
+ * Scoring matrix uses max-per-keyword weights: exact stem (100), stem substring (80),
+ * exact word in subject/topic (70), subject/topic substring (50), description substring (30).
+ */
 export function scoreEntry(entry: CacheEntry, keywords: string[]): number {
   const stem = getFileStem(entry.file).toLowerCase();
   const subject = entry.subject.toLowerCase();
@@ -37,6 +46,13 @@ export function scoreEntry(entry: CacheEntry, keywords: string[]): number {
   return total;
 }
 
+/**
+ * Ranks cache entries by keyword relevance.
+ *
+ * @param entries - Candidate entries to rank.
+ * @param keywords - Search keywords.
+ * @returns Score-sorted entries with zero-score candidates removed.
+ */
 export function rankResults(entries: CacheEntry[], keywords: string[]): CacheEntry[] {
   const scored = entries.map((entry) => ({
     entry,
@@ -52,6 +68,14 @@ export function rankResults(entries: CacheEntry[], keywords: string[]): CacheEnt
   return matched.map((s) => ({ ...s.entry, score: s.score }));
 }
 
+/**
+ * Checks whether a keyword appears as an exact word in text.
+ *
+ * @param text - Candidate text.
+ * @param keyword - Lowercased keyword to match.
+ * @returns `true` when an exact token match exists.
+ * @remarks Word matching is based on split boundaries (`space`, `_`, `-`, `.`, `/`).
+ */
 export function isExactWordMatch(text: string, keyword: string): boolean {
   // Match whole words — split on non-alphanumeric chars
   const words = text.split(/[\s\-_./]+/);

package/src/types/cache.ts

@@ -1,7 +1,11 @@
 import { z } from "zod";
 
+/** Supported cache namespaces exposed by the CLI and plugin tools. */
 export type AgentType = "external" | "local";
 
+/**
+ * Normalized cache entry summary returned by the `list` command prior to formatting.
+ */
 export interface CacheEntry {
   file: string;
   agent: AgentType;
@@ -21,9 +25,16 @@ const HeaderMetaSchema = z.object({
   etag: z.string().optional(),
   last_modified: z.string().optional(),
   checked_at: z.string(),
+  // "unchecked" = entry written without HTTP check
   status: z.enum(["fresh", "stale", "unchecked"]),
 });
 
+/** Stored HTTP validator metadata for one source URL in an external cache entry. */
+export type HeaderMeta = z.infer<typeof HeaderMetaSchema>;
+
+/**
+ * Validates external context cache JSON files stored under `.ai/external-context-gatherer_cache/`.
+ */
 export const ExternalCacheFileSchema = z.looseObject({
   subject: z.string(),
   description: z.string(),
@@ -32,12 +43,22 @@ export const ExternalCacheFileSchema = z.looseObject({
   header_metadata: z.record(z.string(), HeaderMetaSchema),
 });
 
+/** Validates one tracked file baseline used by local file-change detection. */
 export const TrackedFileSchema = z.object({
   path: z.string(),
   mtime: z.number(),
   hash: z.string().optional(),
 });
 
+const FileFactsSchema = z.object({
+  summary: z.string().max(300).optional(),
+  role: z
+    .enum(["entry-point", "interface", "implementation", "test", "config"])
+    .optional(),
+  importance: z.union([z.literal(1), z.literal(2), z.literal(3)]).optional(),
+  facts: z.array(z.string().max(300)).max(10).optional(),
+});
+
 /**
  * Zod schema for the local context-gatherer cache file (`context.json`).
  *
@@ -47,8 +68,8 @@ export const TrackedFileSchema = z.object({
  * Size constraints enforced at write time:
  * - `global_facts`: max 20 entries; each string ≤ 300 characters.
  *   For cross-cutting structural observations only (e.g. repo layout, toolchain).
- * - `facts`: max 30 entries per file path; each string ≤ 800 characters.
- *   Facts must be concise observations — not raw file content or code snippets.
+ * - `facts`: per-file structured metadata with max 10 concise fact strings
+ *   (each string ≤ 300 characters).
  */
 export const LocalCacheFileSchema = z.looseObject({
   timestamp: z.string(),
@@ -68,24 +89,27 @@ export const LocalCacheFileSchema = z.looseObject({
         "max 20 global facts — choose only cross-cutting structural observations",
     })
     .optional(),
-  facts: z
-    .record(
-      z.string(),
-      z
-        .array(
-          z.string().max(800, {
-            message:
-              "write concise observations, not file content (max 800 chars per fact)",
-          }),
-        )
-        .max(30, {
-          message:
-            "max 30 facts per file — choose the most architecturally meaningful observations",
-        }),
-    )
-    .optional(),
+  facts: z.record(z.string(), FileFactsSchema).optional(),
+  modules: z.record(z.string(), z.array(z.string())).optional(),
 });
 
 export type TrackedFile = z.infer<typeof TrackedFileSchema>;
+export type FileFacts = z.infer<typeof FileFactsSchema>;
 export type ExternalCacheFile = z.infer<typeof ExternalCacheFileSchema>;
 export type LocalCacheFile = z.infer<typeof LocalCacheFileSchema>;
+
+const GraphNodeSchema = z.object({
+  rank: z.number(),
+  deps: z.array(z.string()),
+  defs: z.array(z.string()),
+});
+
+/**
+ * Validates graph cache payloads written by `watch` and consumed by `graph`.
+ */
+export const GraphCacheFileSchema = z.object({
+  files: z.record(z.string(), GraphNodeSchema),
+  computed_at: z.string(),
+});
+
+export type GraphCacheFile = z.infer<typeof GraphCacheFileSchema>;