deepseek-web-retrieval 0.8.0 → 0.10.0

package/src/core/search.ts

@@ -1,25 +1,103 @@
+import { MAX_QUERY_CHARS } from "./constants";
 import { normalizeDomains } from "./domains";
 import { truncate } from "./format";
 import type { DeepSeekSearchResult, SearchOptions, SearchResult } from "./types";
 import { normalizeResultUrl } from "./url";
 
+/** The fewest body characters a degraded query keeps before operators start dropping. */
+const MIN_BODY_CHARS = 8;
+
+function charCount(value: string): number {
+  return Array.from(value).length;
+}
+
+/** The query string plus every adjustment made to fit it under the length limit. */
+export interface ComposedQuery {
+  readonly query: string;
+  readonly notes: readonly string[];
+}
+
+interface OperatorParts {
+  readonly blocked: readonly string[];
+  readonly include?: string;
+  readonly language?: string;
+}
+
 /**
- * Appends DeepSeek search operators:
- *   blocked: -site:example.com (space separated for multiple)
- *   include: site:a.com OR site:b.com
- *   language: lang:zh or lang:zh,en
+ * Operators are official API surface, documented in the guide's search-syntax
+ * section (搜索语法): site:, -site:, lang:, quoted phrases, after:/before:.
  */
-export function buildQuery(
+function operatorParts(options: Pick<SearchOptions, "blockedDomains" | "includeDomains" | "language">): OperatorParts {
+  const blocked = normalizeDomains(options.blockedDomains).map((domain) => `-site:${domain}`);
+  const include = normalizeDomains(options.includeDomains).map((domain) => `site:${domain}`);
+  const language = options.language?.trim().replace(/^lang:/i, "");
+  return {
+    blocked,
+    include: include.length ? include.join(" OR ") : undefined,
+    language: language ? `lang:${language}` : undefined,
+  };
+}
+
+function assemble(body: string, parts: OperatorParts, withInclude: boolean, withLang: boolean): string {
+  const segments = [body, ...parts.blocked];
+  if (withInclude && parts.include) segments.push(parts.include);
+  if (withLang && parts.language) segments.push(parts.language);
+  return segments.filter((segment) => segment.length > 0).join(" ");
+}
+
+/** Characters left for the query body once the kept operators and separators are paid for. */
+function bodyBudget(parts: OperatorParts, withInclude: boolean, withLang: boolean, maxChars: number): number {
+  const fixed = [
+    ...parts.blocked,
+    ...(withInclude && parts.include ? [parts.include] : []),
+    ...(withLang && parts.language ? [parts.language] : []),
+  ].join(" ");
+  return maxChars - (fixed ? charCount(fixed) + 1 : 0);
+}
+
+/**
+ * Builds the wire query within the API's character budget, degrading instead of
+ * failing when operators push it over: the query body is truncated first (user
+ * configuration outranks model verbosity), the language filter drops next, the
+ * include list last; blocked domains never drop. Only when the -site:
+ * operators alone crowd out the body does the call fail. Every adjustment is
+ * reported in `notes` so the model can be shown what was actually searched.
+ */
+export function composeSearchQuery(
   query: string,
   options: Pick<SearchOptions, "blockedDomains" | "includeDomains" | "language">,
-): string {
-  const parts = [query.trim()];
-  for (const domain of normalizeDomains(options.blockedDomains)) parts.push(`-site:${domain}`);
-  const include = normalizeDomains(options.includeDomains);
-  if (include.length) parts.push(include.map((domain) => `site:${domain}`).join(" OR "));
-  const language = options.language?.trim().replace(/^lang:/i, "");
-  if (language) parts.push(`lang:${language}`);
-  return parts.filter((part) => part.length > 0).join(" ");
+  maxChars: number = MAX_QUERY_CHARS,
+): ComposedQuery {
+  const parts = operatorParts(options);
+  const body = query.trim();
+  const notes: string[] = [];
+
+  const attempt = (withInclude: boolean, withLang: boolean): string | undefined => {
+    const budget = bodyBudget(parts, withInclude, withLang, maxChars);
+    if (charCount(body) <= budget) return assemble(body, parts, withInclude, withLang);
+    if (budget >= MIN_BODY_CHARS) {
+      notes.push(`query truncated to ${budget} characters (query length limit)`);
+      return assemble(truncate(body, budget), parts, withInclude, withLang);
+    }
+    return undefined;
+  };
+
+  let assembled = attempt(true, true);
+  if (assembled === undefined && parts.language) {
+    notes.push("language filter dropped (query length limit)");
+    assembled = attempt(true, false);
+  }
+  if (assembled === undefined && parts.include) {
+    notes.push("includeDomains filter dropped (query length limit)");
+    assembled = attempt(false, false);
+  }
+  if (assembled === undefined) {
+    throw new Error(
+      `DeepSeek search query cannot fit ${maxChars} characters: the blockedDomains -site: ` +
+        `operators alone occupy ${charCount(parts.blocked.join(" "))} characters`,
+    );
+  }
+  return { query: assembled, notes };
 }
 
 export function parsePublished(value: unknown): number | undefined {
@@ -64,7 +142,20 @@ export function processResults(raw: readonly DeepSeekSearchResult[], options: Se
     }
 
     seen.add(url);
-    const content = truncate(optionalText(item.summary) ?? optionalText(item.snippet) ?? "", options.maxSummaryChars);
+    // A need_content page body outranks the digest — the summary is only ever
+    // a proxy for the body it compresses. A zero budget drops the body so the
+    // digest renders instead.
+    const body = optionalText(item.content);
+    const digest = optionalText(item.summary) ?? optionalText(item.snippet) ?? "";
+    const fromPage = body !== undefined && options.contentMaxChars > 0;
+    const rawContent: string = fromPage && body !== undefined ? body : digest;
+    const contentBudget = fromPage ? options.contentMaxChars : options.maxSummaryChars;
+    const cutContent = truncate(rawContent, contentBudget);
+    // The ellipsis marks a summary the cap actually shortened; official
+    // summaries are typically 600-800 characters, so the 1,200 default
+    // rarely triggers it.
+    const content = cutContent && charCount(rawContent) > contentBudget ? `${cutContent}…` : cutContent;
+    const contentKind = fromPage ? "page" : "digest";
     const published = parsePublished(item.date);
     const title = optionalText(item.title);
     const rerankScore = typeof rerank === "number" && Number.isFinite(rerank) ? rerank : undefined;
@@ -73,7 +164,7 @@ export function processResults(raw: readonly DeepSeekSearchResult[], options: Se
     results.push({
       url,
       ...(title ? { title } : {}),
-      ...(content ? { content } : {}),
+      ...(content ? { content, contentKind } : {}),
       ...(published !== undefined ? { published } : {}),
       ...(rerankScore !== undefined ? { rerankScore } : {}),
       ...(authorityScore !== undefined ? { authority: authorityScore } : {}),

package/src/core/types.ts

@@ -20,6 +20,14 @@ export interface SearchOptions {
    */
   readonly localization?: string;
   readonly maxSummaryChars: number;
+  /**
+   * Deployment-level only — never a per-call tool parameter. The budget a
+   * need_content page body is clamped to per result; the per-call boolean is
+   * `SearchRequest.needContent`.
+   */
+  readonly contentMaxChars: number;
+  /** Deployment-level only; the timeout a need_content call uses instead of `timeoutMs`. */
+  readonly contentTimeoutMs: number;
   readonly timeoutMs: number;
   readonly enabled: boolean;
 }
@@ -47,6 +55,12 @@ export interface ResolvedOptions {
   readonly fetch: FetchOptions;
   readonly auth: AuthOptions;
   readonly retry: RetryOptions;
+  /**
+   * The API root both retrieval endpoints are composed from. Infrastructure
+   * routing, not a result-shaping knob: proxies and mock upstreams override it;
+   * anything but an http(s) URL is dropped at resolution back to the default.
+   */
+  readonly baseUrl: string;
 }
 
 export interface DeepSeekSearchResult {
@@ -57,6 +71,8 @@ export interface DeepSeekSearchResult {
   readonly url?: string | null;
   readonly snippet?: string | null;
   readonly summary?: string | null;
+  /** The need_content page body; an empty string when need_content is false or the content is unavailable. */
+  readonly content?: string | null;
   readonly date?: string | null;
 }
 
@@ -65,6 +81,8 @@ export interface SearchResult {
   readonly url: string;
   readonly title?: string;
   readonly content?: string;
+  /** Which wire field `content` came from: a need_content page body or the summary/snippet digest. */
+  readonly contentKind?: "page" | "digest";
   readonly published?: number;
   readonly rerankScore?: number;
   /** Faithful to the wire: -1 means unknown authority. */
@@ -72,6 +90,17 @@ export interface SearchResult {
   readonly siteName?: string;
 }
 
+/** What one search call executed: the processed results plus the query actually sent. */
+export interface SearchOutcome {
+  readonly results: readonly SearchResult[];
+  /** The query as the caller provided it, trimmed. */
+  readonly inputQuery: string;
+  /** The query sent to DeepSeek, operators included. */
+  readonly effectiveQuery: string;
+  /** One entry per degradation applied to fit the query budget; empty means nothing was adjusted. */
+  readonly notes: readonly string[];
+}
+
 export interface FetchedPage {
   readonly url: string;
   readonly title: string;

package/src/installer/apply.ts

@@ -5,8 +5,8 @@ import { codecFor, writeConfig } from "./formats";
 import { deepEqual, valueAt } from "./formats/value";
 import { withOperationLock } from "./operation-lock";
 import { acquireFileOwnership, assertFileOwnership, releaseFileOwnership } from "./ownership";
+import { deleteRecord, readRecord, recordPathFor, writeRecord } from "./record";
 import { pruneEmptyDir, revertRecordedFile } from "./revert";
-import { deleteRecord, readRecord, statePathFor, writeRecord } from "./state";
 import type { ConfigOp, FileEdit, InstallerInput, InstallPlan, InstallRecord, RecordedFile } from "./types";
 
 /** What a successful apply reports; every failure mode throws instead. */
@@ -37,7 +37,7 @@ interface PreparedEdit {
  * rendered (the plan and the record must describe one plan-time snapshot —
  * ADR-0001), prepares every edit in memory (a malformed existing config fails
  * before any file is written), writes the files, reverts artifacts orphaned by
- * a tier change, verifies the result, then records surgical-undo state. Write
+ * a tier change, verifies the result, then records the install record. Write
  * and verification failures restore touched files and the previous record.
  * Incomplete recovery is reported explicitly and keeps new ownership claims
  * so another install cannot adopt partially applied configuration.
@@ -46,7 +46,7 @@ export function applyPlan(plan: InstallPlan, input: InstallerInput): ApplyResult
   if (plan.errors.length > 0) {
     throw new Error(`refusing to apply a plan with errors: ${plan.errors.map((error) => error.message).join("; ")}`);
   }
-  return withOperationLock([statePathFor(input)], () =>
+  return withOperationLock([recordPathFor(input)], () =>
     withOperationLock(
       [...plan.edits, ...(plan.reverts ?? [])].map((file) => file.file),
       () => applyLocked(plan, input),
@@ -231,7 +231,7 @@ function rollbackApply(
   try {
     if (previous !== undefined) writeRecord(input, previous);
     else deleteRecord(input);
-    if (previous === undefined ? existsSync(statePathFor(input)) : !deepEqual(readRecord(input), previous)) {
+    if (previous === undefined ? existsSync(recordPathFor(input)) : !deepEqual(readRecord(input), previous)) {
       throw new Error("restored install record differs from its previous state");
     }
   } catch (restoreError) {

package/src/installer/cli.ts

@@ -7,8 +7,8 @@ import { ApplyError, applyPlan } from "./apply";
 import { runConfigCommand } from "./config-command";
 import { HOST_PLANNERS, HOST_VERSION_PROBES, planForHost } from "./hosts";
 import { pinPackageRef } from "./ownership";
+import { legacyGlobalRecordDir, listRecords, readingLegacyGlobalRecords } from "./record";
 import { renderPlan } from "./render";
-import { legacyGlobalStateDir, listRecords, readingLegacyGlobalRecords } from "./state";
 import type { HostName, InstallerInput, Scope, Tier } from "./types";
 import { uninstall } from "./uninstall";
 
@@ -161,7 +161,7 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
     }
     if (readingLegacyGlobalRecords({ ...roots, configHome })) {
       out(
-        `Global install records are being read from the legacy ${legacyGlobalStateDir(roots)} ` +
+        `Global install records are being read from the legacy ${legacyGlobalRecordDir(roots)} ` +
           "(written before the Windows config home moved to %APPDATA%).",
       );
     }

package/src/installer/config-command.ts

@@ -68,17 +68,18 @@ export async function runConfigCommand(
   const client = deps.client ?? createRetrievalClient();
   const startedAt = Date.now();
   try {
-    const results = await client.searchWeb(query, resolved.search, {
+    const outcome = await client.searchWeb(query, resolved.search, {
       signal: new AbortController().signal,
       auth: { apiKey },
       retry: resolved.retry,
+      baseUrl: resolved.baseUrl,
     });
     const elapsedMs = Date.now() - startedAt;
     io.out(
-      `search "${query.trim()}" — ${results.length} ${results.length === 1 ? "result" : "results"} in ${elapsedMs} ms`,
+      `search "${query.trim()}" — ${outcome.results.length} ${outcome.results.length === 1 ? "result" : "results"} in ${elapsedMs} ms`,
     );
     io.out("");
-    for (const line of formatSearchResults(results).split("\n")) io.out(line);
+    for (const line of formatSearchResults(outcome.results, outcome).split("\n")) io.out(line);
     return 0;
   } catch (error) {
     io.err(error instanceof Error ? error.message : String(error));

package/src/installer/hosts/claude-code.ts

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { API_KEY_ENV } from "../../core/constants";
 import { FORCED_COST_NOTE, othersStayRegisteredNote, replacingExistingEntryNote, splitCompetitors } from "../detect";
@@ -8,7 +7,7 @@ import { isPlainObject } from "../formats/value";
 import { join } from "../paths";
 import { MCP_TOOL_IDS, rulesLines } from "../rulesContent";
 import type { ConfigOp, FileEdit, HostPaths, InstallerInput, InstallPlan, InstallRecord } from "../types";
-import { planHeader } from "./shared";
+import { planHeader, probeHostVersion } from "./shared";
 
 /**
  * The Claude Code release this installer's facts are verified against — the lock in
@@ -24,22 +23,9 @@ function valueKind(value: unknown): string {
   return Array.isArray(value) ? "an array" : `a ${typeof value}`;
 }
 
-/**
- * The one subprocess the installer runs: `claude --version`, probed for the
- * version-drift note. A missing binary or unreadable output skips the check with
- * a stderr note and never blocks the plan — honor or report.
- */
+/** Probes `claude --version` for the version-drift note (see probeHostVersion). */
 export function probeClaudeCodeVersion(err: (line: string) => void): string | undefined {
-  // env passed explicitly: runtime PATH edits (tests) must reach the lookup.
-  // shell: npm's global install on Windows provides only a claude.cmd shim,
-  // which spawnSync cannot launch without a shell; the command and args are
-  // hardcoded, so the shell hop is safe.
-  const result = spawnSync("claude", ["--version"], { timeout: 5000, encoding: "utf8", env: process.env, shell: true });
-  const version = result.status === 0 ? parseClaudeCodeVersion(result.stdout ?? "") : undefined;
-  if (version === undefined) {
-    err("note: claude was not found on PATH or printed no version; the version-drift check was skipped");
-  }
-  return version;
+  return probeHostVersion("claude", parseClaudeCodeVersion, err);
 }
 
 /**

package/src/installer/hosts/codex.ts

@@ -1,4 +1,3 @@
-import { spawnSync } from "node:child_process";
 import { API_KEY_ENV } from "../../core/constants";
 import { OPTION_ENV_VARS } from "../../core/env";
 import { FORCED_COST_NOTE, othersStayRegisteredNote, replacingExistingEntryNote, splitCompetitors } from "../detect";
@@ -8,7 +7,7 @@ import { isPlainObject } from "../formats/value";
 import { join } from "../paths";
 import { MCP_TOOL_IDS, RAW_MCP_TOOL_IDS, rulesLines } from "../rulesContent";
 import type { ConfigOp, FileEdit, HostPaths, InstallerInput, InstallPlan, InstallRecord } from "../types";
-import { planHeader } from "./shared";
+import { planHeader, probeHostVersion } from "./shared";
 
 /**
  * The Codex release this installer's facts are verified against — the lock in
@@ -16,22 +15,9 @@ import { planHeader } from "./shared";
  */
 export const CODEX_TESTED_VERSION = "0.163.0";
 
-/**
- * The one subprocess the installer runs: `codex --version`, probed for the
- * version-drift note. A missing binary or unreadable output skips the check with
- * a stderr note and never blocks the plan — honor or report.
- */
+/** Probes `codex --version` for the version-drift note (see probeHostVersion). */
 export function probeCodexVersion(err: (line: string) => void): string | undefined {
-  // env passed explicitly: runtime PATH edits (tests) must reach the lookup.
-  // shell: npm's global install on Windows provides only a codex.cmd shim,
-  // which spawnSync cannot launch without a shell; the command and args are
-  // hardcoded, so the shell hop is safe.
-  const result = spawnSync("codex", ["--version"], { timeout: 5000, encoding: "utf8", env: process.env, shell: true });
-  const version = result.status === 0 ? parseCodexVersion(result.stdout ?? "") : undefined;
-  if (version === undefined) {
-    err("note: codex was not found on PATH or printed no version; the version-drift check was skipped");
-  }
-  return version;
+  return probeHostVersion("codex", parseCodexVersion, err);
 }
 
 /** Parses `codex --version` output (`codex-cli 0.163.0`) into the bare version. */

package/src/installer/hosts/index.ts

@@ -1,7 +1,7 @@
 import { API_KEY_ENV } from "../../core/constants";
 import { deepEqual, isPlainObject } from "../formats/value";
 import { assertFileOwnership, fileOwnershipNotes } from "../ownership";
-import { claimedByOtherScope, InstallRecordError, readRecord } from "../state";
+import { claimedByOtherScope, InstallRecordError, readRecord } from "../record";
 import type { HostName, InstallerInput, InstallPlan, InstallRecord, RecordedFile } from "../types";
 import { planClaudeCode, probeClaudeCodeVersion } from "./claude-code";
 import { planCodex, probeCodexVersion } from "./codex";
@@ -153,7 +153,7 @@ function withSecretGuard(plan: InstallPlan): InstallPlan {
             {
               message:
                 `${edit.file}: the existing value at ${op.path.join(".")} contains a credential-looking key ` +
-                `(${offender}). The installer refuses to snapshot secrets into its state file. Move the key to ` +
+                `(${offender}). The installer refuses to snapshot secrets into its install record. Move the key to ` +
                 `environment indirection ("\${${API_KEY_ENV}}" expansion or env_vars) and re-run.`,
             },
           ],

package/src/installer/hosts/opencode.ts

@@ -4,8 +4,8 @@ import { buildRulesBlock } from "../formats/rules";
 import { isPlainObject } from "../formats/value";
 import { lineageMatcher } from "../ownership";
 import { configHome, join } from "../paths";
+import { appendedByPrevious } from "../record";
 import { rulesLines } from "../rulesContent";
-import { appendedByPrevious } from "../state";
 import type { ConfigOp, FileEdit, HostPaths, InstallerInput, InstallPlan, InstallRecord } from "../types";
 import { planHeader } from "./shared";
 

package/src/installer/hosts/pi.ts

@@ -13,8 +13,8 @@ import { buildRulesBlock } from "../formats/rules";
 import { isPlainObject } from "../formats/value";
 import { lineageMatcher } from "../ownership";
 import { join } from "../paths";
+import { appendedByPrevious } from "../record";
 import { MCP_TOOL_IDS, RAW_MCP_TOOL_IDS, rulesLines } from "../rulesContent";
-import { appendedByPrevious } from "../state";
 import type { ConfigOp, FileEdit, HostPaths, InstallerInput, InstallPlan, InstallRecord, PlanError } from "../types";
 import { planHeader } from "./shared";
 
@@ -37,6 +37,15 @@ function piSourceRef(packageRef: string): string {
   return packageRef.startsWith("npm:") ? packageRef : `npm:${packageRef}`;
 }
 
+/** Both Pi paths write the same rules note; one wording so the paths cannot drift. */
+const rulesUpsertNote = (rules: string) =>
+  `Rules block upserted in ${rules}; Pi loads AGENTS.md context files from the working directory and its parents.`;
+
+/** Forced tier, both paths: with no built-in web tool to displace, routing is de-facto exclusive. */
+const FORCED_NO_BUILTIN_NOTE =
+  "Forced tier: Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (de-facto). " +
+  FORCED_COST_NOTE;
+
 export function planPi(input: InstallerInput, previous: InstallRecord | undefined): InstallPlan {
   return input.path === "mcp" ? planPiMcp(input) : planPiExtension(input, previous);
 }
@@ -169,16 +178,11 @@ function planPiExtension(input: InstallerInput, previous: InstallRecord | undefi
       format: "rules",
       block: buildRulesBlock(input.host, rulesLines(RAW_MCP_TOOL_IDS, input.search, input.fetch)),
     });
-    notes.push(
-      `Rules block upserted in ${paths.rules}; Pi loads AGENTS.md context files from the working directory and its parents.`,
-    );
+    notes.push(rulesUpsertNote(paths.rules));
   }
 
   if (forced) {
-    notes.push(
-      "Forced tier: Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (de-facto). " +
-        FORCED_COST_NOTE,
-    );
+    notes.push(FORCED_NO_BUILTIN_NOTE);
   }
 
   return { host: "pi", scope: input.scope, tiers, edits, notes, errors };
@@ -313,16 +317,11 @@ function planPiMcp(input: InstallerInput): InstallPlan {
       format: "rules",
       block: buildRulesBlock(input.host, rulesLines(MCP_TOOL_IDS, input.search, input.fetch)),
     });
-    notes.push(
-      `Rules block upserted in ${paths.rules}; Pi loads AGENTS.md context files from the working directory and its parents.`,
-    );
+    notes.push(rulesUpsertNote(paths.rules));
   }
 
   if (input.search === "forced" || input.fetch === "forced") {
-    notes.push(
-      "Forced tier: Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (de-facto). " +
-        FORCED_COST_NOTE,
-    );
+    notes.push(FORCED_NO_BUILTIN_NOTE);
   }
 
   return { host: "pi", scope: input.scope, tiers, edits, notes, errors };

package/src/installer/hosts/shared.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { BOTH_CAPABILITIES_OFF, competitorSteeringNote, findCompetitorSteering } from "../detect";
 import { codecFor, type LoadedConfig } from "../formats";
 import type { HostPaths, InstallerInput, PlanError } from "../types";
@@ -34,3 +35,25 @@ export function planHeader(input: InstallerInput, paths: HostPaths, loaded: Load
   if (steering.length > 0) notes.push(competitorSteeringNote(paths.rules, steering));
   return { notes, errors, abort: false };
 }
+
+/**
+ * The one subprocess shape the installer runs: `<command> --version`, probed
+ * for the version-drift note. A missing binary or unreadable output skips the
+ * check with a stderr note and never blocks the plan — honor or report.
+ * env is passed explicitly: runtime PATH edits (tests) must reach the lookup.
+ * The shell hop is required because npm's global install on Windows provides
+ * only a .cmd shim, which spawnSync cannot launch without a shell; the command
+ * and args are hardcoded, so it is safe.
+ */
+export function probeHostVersion(
+  command: string,
+  parse: (output: string) => string | undefined,
+  err: (line: string) => void,
+): string | undefined {
+  const result = spawnSync(command, ["--version"], { timeout: 5000, encoding: "utf8", env: process.env, shell: true });
+  const version = result.status === 0 ? parse(result.stdout ?? "") : undefined;
+  if (version === undefined) {
+    err(`note: ${command} was not found on PATH or printed no version; the version-drift check was skipped`);
+  }
+  return version;
+}

package/src/installer/ownership.ts

@@ -1,8 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { isPlainObject } from "../core/object";
+import { recordPathFor, recordReadPath } from "./record";
 import { pruneEmptyDir } from "./revert";
-import { recordReadPath, statePathFor } from "./state";
 import type { InstallerInput, RecordedFile, Scope } from "./types";
 
 type ClaimedFile = Pick<RecordedFile, "file" | "format" | "shared">;
@@ -70,7 +70,7 @@ export function canonicalPath(file: string): string {
 }
 
 function ownerOf(input: InstallerInput): FileOwner {
-  return { recordPath: canonicalPath(statePathFor(input)), scope: input.scope, cwd: canonicalPath(input.cwd) };
+  return { recordPath: canonicalPath(recordPathFor(input)), scope: input.scope, cwd: canonicalPath(input.cwd) };
 }
 
 /**

package/src/installer/paths.ts

@@ -18,8 +18,8 @@ export function configHome(roots: FsRoots): string {
   return roots.configHome ?? join(roots.home, ".config");
 }
 
-/** State records live with their scope: global installs under the config home, project installs in the checkout. */
-export function stateDir(roots: FsRoots, scope: Scope): string {
+/** Install records live with their scope: global installs under the config home, project installs in the checkout. */
+export function recordDir(roots: FsRoots, scope: Scope): string {
   return scope === "global"
     ? join(configHome(roots), "deepseek-web-retrieval")
     : join(roots.cwd, ".deepseek-web-retrieval");

package/src/installer/{state.ts → record.ts}

@@ -1,12 +1,12 @@
 import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { z } from "zod/v4";
-import { stateDir } from "./paths";
+import { recordDir } from "./paths";
 import { atomicWrite } from "./persistence";
 import type { FsRoots, InstallerInput, InstallRecord, Scope } from "./types";
 
-export function statePathFor(input: InstallerInput): string {
-  return join(stateDir(input, input.scope), `install.${input.host}.json`);
+export function recordPathFor(input: InstallerInput): string {
+  return join(recordDir(input, input.scope), `install.${input.host}.json`);
 }
 
 /** The platform a read resolves for: injected at the CLI edge, process.platform otherwise. */
@@ -19,19 +19,19 @@ function platformOf(roots: FsRoots): NodeJS.Platform {
  * home moved to %APPDATA% live under `~/.config`. Kept readable so `list` and
  * `uninstall` keep tracking installs made by older releases.
  */
-export function legacyGlobalStateDir(roots: FsRoots): string {
+export function legacyGlobalRecordDir(roots: FsRoots): string {
   return join(roots.home, ".config", "deepseek-web-retrieval");
 }
 
 /**
- * The file a record is read from: the canonical state path, except that a
+ * The file a record is read from: the canonical record path, except that a
  * missing win32 global record falls back to the legacy `~/.config` location
- * (see legacyGlobalStateDir). Writes always target the canonical path.
+ * (see legacyGlobalRecordDir). Writes always target the canonical path.
  */
 export function recordReadPath(input: InstallerInput, platform: NodeJS.Platform = platformOf(input)): string {
-  const canonical = statePathFor(input);
+  const canonical = recordPathFor(input);
   if (platform !== "win32" || input.scope !== "global" || existsSync(canonical)) return canonical;
-  const legacy = join(legacyGlobalStateDir(input), `install.${input.host}.json`);
+  const legacy = join(legacyGlobalRecordDir(input), `install.${input.host}.json`);
   return existsSync(legacy) ? legacy : canonical;
 }
 
@@ -74,7 +74,7 @@ export class InstallRecordError extends Error {
   ) {
     super(
       `${kind === "invalid" ? "Invalid install record" : "Cannot read install record"} at ${file} (${detail}). ` +
-        "Restore a valid record from backup or repair its permissions before retrying; configuration was not changed. Do not delete undo state to bypass this check.",
+        "Restore a valid install record from your own copy or repair its permissions before retrying; configuration was not changed. Do not delete the install record to bypass this check.",
     );
     this.name = "InstallRecordError";
   }
@@ -131,7 +131,7 @@ export function claimedByOtherScope(input: InstallerInput, files: readonly strin
  * owner-only permissions regardless of umask.
  */
 export function writeRecord(input: InstallerInput, record: InstallRecord): void {
-  const file = statePathFor(input);
+  const file = recordPathFor(input);
   atomicWrite(file, `${JSON.stringify(record, null, 2)}\n`, 0o600);
 }
 
@@ -189,14 +189,14 @@ function hasRecordFiles(dir: string): boolean {
  */
 export function readingLegacyGlobalRecords(roots: FsRoots): boolean {
   if (platformOf(roots) !== "win32") return false;
-  if (hasRecordFiles(stateDir(roots, "global"))) return false;
-  return hasRecordFiles(legacyGlobalStateDir(roots));
+  if (hasRecordFiles(recordDir(roots, "global"))) return false;
+  return hasRecordFiles(legacyGlobalRecordDir(roots));
 }
 
 /** Lists install records found in both scope locations for the given roots. */
 export function listRecords(roots: FsRoots): InstallRecord[] {
-  const global = readRecordsFromDir(stateDir(roots, "global"), "global");
-  const project = readRecordsFromDir(stateDir(roots, "project"), "project");
-  const legacy = readingLegacyGlobalRecords(roots) ? readRecordsFromDir(legacyGlobalStateDir(roots), "global") : [];
+  const global = readRecordsFromDir(recordDir(roots, "global"), "global");
+  const project = readRecordsFromDir(recordDir(roots, "project"), "project");
+  const legacy = readingLegacyGlobalRecords(roots) ? readRecordsFromDir(legacyGlobalRecordDir(roots), "global") : [];
   return [...global, ...legacy, ...project];
 }

package/src/installer/types.ts

@@ -105,7 +105,7 @@ export interface PlanError {
 }
 
 export interface InstallPlan {
-  /** Plan-time undo state; apply rejects a plan superseded by another operation. */
+  /** The plan-time install record; apply rejects a plan superseded by another operation. */
   readonly previousRecord?: InstallRecord;
   readonly host: HostName;
   readonly scope: Scope;

package/src/installer/uninstall.ts

@@ -1,9 +1,9 @@
 import { codecFor } from "./formats";
 import { withOperationLock } from "./operation-lock";
 import { assertFileOwnership, releaseFileOwnership } from "./ownership";
-import { stateDir } from "./paths";
+import { recordDir } from "./paths";
+import { claimedByOtherScope, deleteRecord, readRecord, recordPathFor } from "./record";
 import { pruneEmptyDir, revertRecordedFile } from "./revert";
-import { claimedByOtherScope, deleteRecord, readRecord, statePathFor } from "./state";
 import type { InstallerInput, InstallRecord } from "./types";
 
 /**
@@ -13,7 +13,7 @@ import type { InstallerInput, InstallRecord } from "./types";
  * rules blocks are removed, and files the installer created are deleted.
  */
 export function uninstall(input: InstallerInput): string[] {
-  return withOperationLock([statePathFor(input)], () => {
+  return withOperationLock([recordPathFor(input)], () => {
     const record = readRecord(input);
     if (record === undefined) {
       throw new Error(`No ${input.host} install is recorded for the ${input.scope} scope.`);
@@ -53,7 +53,7 @@ function uninstallLocked(input: InstallerInput, record: InstallRecord): string[]
   // to still exist on disk.
   releaseFileOwnership(input, record.files);
   deleteRecord(input);
-  pruneEmptyDir(stateDir(input, input.scope));
+  pruneEmptyDir(recordDir(input, input.scope));
   lines.push(`removed install record (${input.host}, ${input.scope})`);
   return lines;
 }