@remnic/core 9.32.0 → 9.34.0

package/src/tool-scoped-memory.test.ts

@@ -0,0 +1,199 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  referencesAgentSpecificTool,
+  shouldPromoteGlobalFactToShared,
+  withholdToolScopedFromSharedNamespace,
+} from "./tool-scoped-memory.js";
+
+// ---------------------------------------------------------------------------
+// referencesAgentSpecificTool — table-driven, both polarities.
+//
+// Tuning bias (issue #2183): a FALSE POSITIVE is cheap (the fact stays in the
+// narrower namespace — the documented safe default); a FALSE NEGATIVE is the
+// cross-integration tool-collision bug. Detection leans permissive but must not
+// fire on ordinary prose. Keywords and generic names are word-anchored so
+// "tooling"/"commander" and the "search" inside "research" do not match.
+// ---------------------------------------------------------------------------
+
+const REF_CASES: Array<{ content: string; expected: boolean; note: string }> = [
+  // ---- MUST match --------------------------------------------------------
+  { content: "Prefer the search tool and provide a path when locating code.", expected: true, note: "generic name adjacent to 'tool'" },
+  { content: "Use the `read` tool before editing a file.", expected: true, note: "backticked token adjacent to 'tool'" },
+  { content: "The exec tool requires an absolute cwd.", expected: true, note: "generic name 'exec' adjacent to 'tool'" },
+  { content: "Use `search` when locating code.", expected: true, note: "imperative invocation + backticked identifier" },
+  { content: "Run `rg` before editing.", expected: true, note: "imperative invocation + backticked identifier" },
+  { content: "Use /search with a path.", expected: true, note: "slash-command syntax" },
+  // ---- MUST NOT match ----------------------------------------------------
+  { content: "User prefers dark mode in all editors", expected: false, note: "portable preference; no tool/command context" },
+  { content: "PostgreSQL 15 requires the uuid-ossp extension for gen_random_uuid()", expected: false, note: "portable framework knowledge" },
+  { content: "Magento 2.4.8 has a race condition in checkout", expected: false, note: "'condition' is not a keyword; 'checkout' is not generic" },
+  { content: "The user reads documentation before starting a task", expected: false, note: "the bare verb 'reads' is not a tool reference" },
+  { content: "Search tooling improves developer productivity", expected: false, note: "'tool' must not match the prefix of 'tooling'" },
+  { content: "Research tool improves accuracy", expected: false, note: "'search' must not match inside 'research'" },
+];
+
+for (const { content, expected, note } of REF_CASES) {
+  test(`referencesAgentSpecificTool: ${expected ? "detects" : "ignores"} "${content.slice(0, 44)}…" (${note})`, () => {
+    assert.equal(referencesAgentSpecificTool(content), expected, note);
+  });
+}
+
+const EXTRA_POSITIVE: string[] = [
+  "The `checkout` command switches branches.",
+  "The browser tool navigates to the URL first.",
+  "Always run the memory tool after a context switch.",
+  "the tool named search returns repo hits",
+  "Pi exposes a search tool; OpenClaw exposes a same-named web tool.",
+  "Invoke `memory_store` to persist the reflection.",
+  "Use search when locating implementation",
+  "Run rg before editing",
+  "Call memory_store to persist the result",
+  "Run grep before editing",
+  "Use curl to fetch the URL",
+  "The memory_store tool persists results",
+  "Use the grep command to search files",
+  "Call memory_store() to persist the result",
+  "Use search() when locating code",
+  "Run rg() to find symbols",
+  "Use --force when reinstalling",
+  "The --format cli flag selects JSON",
+  "Run rg --files before editing",
+  "Use grep -n TODO when reviewing",
+  "Run `rg --files` before editing",
+  "The Bash tool executes commands",
+  "Use the Edit tool before saving",
+  "The WebFetch tool retrieves pages",
+  "Run git status before committing",
+  "Use npm install to add dependencies",
+  "The Bash Tool executes commands",
+  "Run git checkout -b feature before editing",
+  "Run `git status` before committing",
+  "Use `npm install` to add dependencies",
+  "Run `git checkout -b feature` before editing",
+  "Use edit before saving",
+  "Use bashExecution before editing",
+  "The bashExecution tool executes commands",
+  "Call bashExecution() to persist data",
+  "Use /remnic flush before reset",
+  "The /remnic command controls memory",
+  "Use `/remnic flush` before reset",
+  "Use `search --path src` when locating code",
+];
+for (const content of EXTRA_POSITIVE) {
+  test(`referencesAgentSpecificTool detects: "${content.slice(0, 44)}…"`, () => {
+    assert.equal(referencesAgentSpecificTool(content), true);
+  });
+}
+
+const EXTRA_NEGATIVE: string[] = [
+  "Git is a useful tool for version control.",
+  "The command line is faster than the GUI for this workflow.",
+  "She has a good command of the deployment process.",
+  "Communication is the main tool of a leader.",
+  "PostgreSQL read replicas lag under heavy load.",
+  "Memory usage spikes during compaction.",
+  "The browser caches static assets aggressively.",
+  "Reading long files is slow.",
+  "He writes detailed notes after every meeting.",
+  "Leadership requires command of the subject matter.",
+  "Writers use memory and emotion to craft stories.",
+  "I use search engines daily for research.",
+  "Use memory wisely and rest often.",
+  "Visit https://example.com/search for docs.",
+  "The service reads configuration from /etc/remnic/config.json",
+  "Logs live under /var/log/remnic",
+  "Restore the backup from /tmp/dump.sql",
+  "Use /etc/remnic/config.json for configuration",
+  "The service should use /health for readiness checks",
+  "Use PostgreSQL for durable storage",
+  "Use TypeScript in new packages",
+  "Run migrations after deployment",
+  "Use Redis for caching",
+  "Use 'least privilege' when designing authorization",
+  'Run "database migrations" after deployment',
+  "Use SQL for analytics",
+  "Use API for integration",
+  "Use Go for backend services",
+  "Use `/etc/remnic/config.json` for configuration",
+  "Run `/var/log/remnic` cleanup",
+  "Call me before you leave",
+  "Use it to simplify the workflow",
+  "Run in before deploying",
+  "Use 2024-2025 data for the baseline",
+  "The tool — a recent addition — is optional",
+  "Use `TypeScript` for new packages",
+  "Use `config.json` for configuration",
+  "Use `/health` for readiness checks",
+  "Writers use edit passes",
+  "Use macOS for development",
+  "Use iOS for mobile apps",
+  "Use eBay for purchases",
+  "Automation tool reduces repetitive work",
+  "Encryption tool selection should follow the threat model",
+  "Monitoring tool availability affects reliability",
+  "Use user_id in API responses",
+  "Use database_name for the connection",
+  "Use feature_flag when rolling out changes",
+  "Use least-privilege when designing authorization",
+  "Use TypeScript-first for new packages",
+];
+for (const content of EXTRA_NEGATIVE) {
+  test(`referencesAgentSpecificTool ignores prose: "${content.slice(0, 44)}…"`, () => {
+    assert.equal(referencesAgentSpecificTool(content), false);
+  });
+}
+
+test("referencesAgentSpecificTool: empty/non-string input is false (no throw)", () => {
+  assert.equal(referencesAgentSpecificTool(""), false);
+  assert.equal(referencesAgentSpecificTool("   "), false);
+});
+
+// ---------------------------------------------------------------------------
+// shouldPromoteGlobalFactToShared — composed scope-routing predicate.
+// ---------------------------------------------------------------------------
+
+const PROMOTION_CASES: Array<{ name: string; args: { scope: string | null | undefined; content: string; sourceConnector?: string; procedureSteps?: ReadonlyArray<{ intent?: string; toolCall?: { kind?: string; signature?: string } }> }; expected: boolean }> = [
+  { name: "global portable fact, no connector -> promote", args: { scope: "global", content: "User prefers dark mode in all editors" }, expected: true },
+  { name: "global tool-scoped fact WITH connector -> withhold (#2183)", args: { scope: "global", content: "Prefer the search tool when locating code.", sourceConnector: "pi" }, expected: false },
+  { name: "global tool-scoped fact, no knob -> withheld when connector known", args: { scope: "global", content: "The exec tool requires an absolute cwd.", sourceConnector: "openclaw" }, expected: false },
+  { name: "global tool-scoped fact WITHOUT connector -> promote (unattributed)", args: { scope: "global", content: "Prefer the search tool when locating code." }, expected: true },
+  { name: "project-scoped fact -> never promote via this path", args: { scope: "project", content: "Prefer the search tool when locating code.", sourceConnector: "pi" }, expected: false },
+  { name: "empty connector string is treated as unknown -> promote", args: { scope: "global", content: "Prefer the search tool when locating code.", sourceConnector: "" }, expected: true },
+  { name: "global portable-title procedure with tool-bearing steps + connector -> withhold (#2183 P2, scope-routing)", args: { scope: "global", content: "Workflow for locating implementation", sourceConnector: "pi", procedureSteps: [{ intent: "find the symbol", toolCall: { kind: "search", signature: "search('foo')" } }, { intent: "open the file", toolCall: { kind: "read", signature: "read('bar')" } }] }, expected: false },
+];
+for (const { name, args, expected } of PROMOTION_CASES) {
+  test(`shouldPromoteGlobalFactToShared: ${name}`, () => {
+    assert.equal(shouldPromoteGlobalFactToShared(args), expected);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// withholdToolScopedFromSharedNamespace — the SINGLE primitive every shared-
+// namespace promotion path consults. Includes structured procedure tool
+// identity (issue #2183 P2): a portable title + tool-bearing steps withholds.
+// ---------------------------------------------------------------------------
+
+const WITHHOLD_CASES: Array<{
+  name: string;
+  args: { content: string; sourceConnector?: string; procedureSteps?: ReadonlyArray<{ intent?: string; toolCall?: { kind?: string; signature?: string } }> };
+  expected: boolean;
+}> = [
+  { name: "tool-scoped + connector -> withhold", args: { content: "Prefer the search tool when locating code.", sourceConnector: "pi" }, expected: true },
+  { name: "tool-scoped + empty connector -> do not withhold", args: { content: "Prefer the search tool when locating code.", sourceConnector: "" }, expected: false },
+  { name: "tool-scoped + whitespace-only connector -> do not withhold", args: { content: "Prefer the search tool when locating code.", sourceConnector: "   " }, expected: false },
+  { name: "tool-scoped + no connector -> do not withhold", args: { content: "Prefer the search tool when locating code." }, expected: false },
+  { name: "portable + connector -> do not withhold", args: { content: "User prefers dark mode in all editors", sourceConnector: "pi" }, expected: false },
+  { name: "portable title + connector + tool-bearing steps -> withhold (#2183 P2)", args: { content: "When locating implementation", sourceConnector: "pi", procedureSteps: [{ intent: "find", toolCall: { kind: "search", signature: "search('foo')" } }] }, expected: true },
+  { name: "portable title + connector + steps without toolCall -> do not withhold", args: { content: "When locating implementation", sourceConnector: "pi", procedureSteps: [{ intent: "read the docs" }] }, expected: false },
+  { name: "portable title + connector + steps with empty kind -> do not withhold", args: { content: "When locating implementation", sourceConnector: "pi", procedureSteps: [{ intent: "x", toolCall: { kind: "  ", signature: "y" } }] }, expected: false },
+  { name: "tool-bearing steps but NO connector -> do not withhold (unattributed)", args: { content: "When locating implementation", procedureSteps: [{ intent: "find", toolCall: { kind: "search", signature: "search('foo')" } }] }, expected: false },
+  { name: "portable title + intent-only tool step + connector -> withhold (#2183 intent text)", args: { content: "Workflow for locating implementation", sourceConnector: "pi", procedureSteps: [{ intent: "Run grep before editing" }] }, expected: true },
+  { name: "portable title + all-portable steps + connector -> do not withhold", args: { content: "Workflow for code review", sourceConnector: "pi", procedureSteps: [{ intent: "Read the changes carefully" }, { intent: "Approve the work" }] }, expected: false },
+];
+for (const { name, args, expected } of WITHHOLD_CASES) {
+  test(`withholdToolScopedFromSharedNamespace: ${name}`, () => {
+    assert.equal(withholdToolScopedFromSharedNamespace(args), expected);
+  });
+}

package/src/tool-scoped-memory.ts

@@ -0,0 +1,190 @@
+/**
+ * Tool-scoped memory guard (issue #2183).
+ *
+ * A tool-related fact extracted from a specific agent integration carries an
+ * UNQUALIFIED tool name — "use the search tool" — with no agent identity
+ * attached (the conversation handed to the extraction LLM is rendered as
+ * `[role] content` only). Promoting such a fact to the shared namespace lets a
+ * DIFFERENT integration that exposes a same-named but incompatible tool (Pi
+ * `search` = repo code search vs OpenClaw `search` = web search) consume it.
+ *
+ * `referencesAgentSpecificTool` flags fact text that references a specific
+ * tool/command invocation rather than portable knowledge. The promotion guard
+ * in `orchestration/extraction-persist.ts` uses it — when the producing
+ * integration is known (`sourceConnector`) — to keep such a fact in that
+ * integration's own namespace.
+ *
+ * Tuning bias: a FALSE POSITIVE is cheap — the fact stays in the narrower
+ * namespace, the documented safe default. A FALSE NEGATIVE is the actual
+ * cross-integration collision bug, so detection leans permissive — but it must
+ * not fire on ordinary prose.
+ */
+
+const BT = "`";
+
+// Generic tool names + host-tool names emitted by the agent adapters.
+// Evidence: "edit" — Pi messages.test.ts:43 ({ type: "toolCall", name: "edit" }).
+// "bash" — Pi messages.test.ts:70 (bashExecution tool rendering). "glob",
+// "webfetch", "task" — standard Claude Code tools (Pi wraps Claude Code).
+const GENERIC_TOOL_NAMES = [
+  "read", "write", "search", "fetch", "browser", "exec", "shell", "memory",
+  "edit", "bash", "glob", "webfetch", "task",
+  "remnic",
+];
+const KNOWN_CLI_NAMES = [
+  "grep", "curl", "git", "npm", "pnpm", "sed", "awk", "jq", "cat", "ssh",
+  "docker", "kubectl", "make", "rg", "ls", "cd",
+];
+const GENERIC_NAMES_ALT = GENERIC_TOOL_NAMES.join("|");
+const KNOWN_NAMES_ALT = [...GENERIC_TOOL_NAMES, ...KNOWN_CLI_NAMES].join("|");
+const CLI_NAMES_ALT = KNOWN_CLI_NAMES.join("|");
+
+const FS_ROOTS = "(?:etc|var|usr|tmp|home|opt|srv|proc|dev)";
+const FLAG = "(?:--|-)[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*\\b";
+const FLAG_NAKED = "(?:--|-)[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)*";
+const OPCODE = "[A-Za-z0-9_./-]{1,20}";
+
+const NO_SLASH_TOKEN = "[A-Za-z0-9_.-]{1,60}";
+const SLASH_CMD_TOKEN = "/(?:" + GENERIC_NAMES_ALT + ")\\b";
+const QUOTED_CONTENT = "(?:" + NO_SLASH_TOKEN + "|" + SLASH_CMD_TOKEN + ")";
+const QUOTED_PERMISSIVE =
+  "(?:" + BT + QUOTED_CONTENT + BT + "|\"" + QUOTED_CONTENT + "\"|'" + QUOTED_CONTENT + "')";
+
+const SNAKE = "(?:[a-z][a-z0-9]*(?:_[a-z0-9]+)+)\\b";
+const SNAKE_NON_DATA = "(?:[a-z][a-z0-9]*(?:_[a-z0-9]+)*(?:_(?!id\\b|name\\b|flag\\b|count\\b|at\\b|url\\b|key\\b|type\\b)[a-z0-9]+))\\b";
+const SNAKE_KEBAB = "(?:[a-z][a-z0-9]*(?:[_-][a-z0-9]+)+)\\b";
+
+const KNOWN_NAMES_CI = "\\b(?:" + KNOWN_NAMES_ALT + ")\\b";
+const CLI_NAMES_CI = "\\b(?:" + CLI_NAMES_ALT + ")\\b";
+const KEYWORD = "\\b(?:mcp[ _]tool|slash[ _]command|cli[ _]flag|subcommand|tool|command)\\b";
+
+const IDENT = "(?:" + QUOTED_PERMISSIVE + "|" + KNOWN_NAMES_CI + "|" + SNAKE_KEBAB + "|" + FLAG + ")";
+
+const IMM = "[\\s'\"" + BT + "]{1,4}";
+const CONN = "\\s+(?:named|called|aka)\\s+";
+const VERB = "\\b(?:use|run|call|invoke)\\b";
+const SLASH_GENERIC = "/(?:" + GENERIC_NAMES_ALT + ")\\b";
+const CLAUSE_BOUNDARY = "(?:$|[.,;(:]|(?:when|before|after|to|with|for|on|in|if|unless|whenever)\\b)";
+const ARGS = "(?:\\s+" + FLAG + "(?:\\s+" + OPCODE + "){0,4})?";
+const CLI_ARG_TOKEN = "(?:[a-z][a-z0-9-]{0,15}|" + FLAG_NAKED + "|" + OPCODE + ")";
+const CLI_ARG_RUN = "(?:\\s+" + CLI_ARG_TOKEN + "){1,4}";
+
+// Shared: a CLI tool or slash command optionally followed by a bounded
+// argument run. Used by BOTH the quoted and unquoted invocation arms so
+// quoting cannot diverge from unquoted again (#2183 round 20).
+const CMD_WITH_ARGS = "(?:(?:" + CLI_NAMES_CI + "|" + SLASH_GENERIC + ")" + CLI_ARG_RUN + ")";
+const QSTRICT_CONTENT =
+  "(?:" + KNOWN_NAMES_ALT + "|[a-z][a-z0-9]*(?:[_-][a-z0-9]+)+" + "|" + FLAG_NAKED + "|" + SLASH_CMD_TOKEN +
+  "|" + CMD_WITH_ARGS + "|(?:" + KNOWN_NAMES_ALT + ")" + CLI_ARG_RUN + ")";
+const QUOTED_STRICT =
+  "(?:" + BT + QSTRICT_CONTENT + BT + "|\"" + QSTRICT_CONTENT + "\"|'" + QSTRICT_CONTENT + "')";
+
+const INVOCATION_FLAG_ARGS =
+  VERB + "\\s+(?:" + QUOTED_STRICT + "|" + KNOWN_NAMES_CI + "|" + SNAKE_NON_DATA + "|" + SLASH_GENERIC + "|" + FLAG + ")" + ARGS + "(?=\\s*" + CLAUSE_BOUNDARY + ")";
+const INVOCATION_CLI_ARGS =
+  VERB + "\\s+" + CMD_WITH_ARGS + "(?=\\s*" + CLAUSE_BOUNDARY + ")";
+const INVOCATION = "(?:" + INVOCATION_FLAG_ARGS + "|" + INVOCATION_CLI_ARGS + ")";
+
+const TOOL_REFERENCE_CI = new RegExp(
+  "(?:" +
+    IDENT + IMM + KEYWORD + "|" + KEYWORD + IMM + IDENT + "|" +
+    KEYWORD + CONN + IDENT + "|" + IDENT + CONN + KEYWORD + "|" +
+    INVOCATION +
+  ")",
+  "i",
+);
+
+function hasCapitalisedToolName(content: string): boolean {
+  // Structural discriminator: a capitalised identifier beside a tool/command
+  // keyword qualifies ONLY when preceded by an article or invocation verb (not
+  // sentence-initial), or connected via named/called/aka. This replaces the
+  // blocklist approach — a structural rule beats a growing STOP_WORDS set.
+  for (const re of [
+    /(?:the|a|an|this|that|these|those|use|run|call|invoke)\s+([A-Za-z][A-Za-z0-9]+)\b[\s'`<>]{0,4}\b(?:tool|command|subcommand)\b/gi,
+    /\b(?:tool|command|subcommand)\b\s+(?:named|called|aka)\s+([A-Za-z][A-Za-z0-9]+)\b/gi,
+  ]) {
+    re.lastIndex = 0;
+    let match;
+    while ((match = re.exec(content)) !== null) {
+      const w = match[1];
+      if (w && w[0] >= "A" && w[0] <= "Z") return true;
+    }
+  }
+  return false;
+}
+
+function hasCamelCaseToolName(content: string): boolean {
+  // Case-sensitive: camelCase (lowercase start, interior uppercase) is a common
+  // host-tool naming convention (bashExecution, memoryStore, webFetch). Ordinary
+  // English words are never camelCase, and PascalCase (PostgreSQL, TypeScript)
+  // starts uppercase so is handled by hasCapitalisedToolName instead.
+  const camelRe = /\b([a-z]{3,}[a-z0-9]*[A-Z][a-z][A-Za-z0-9]*)\b/g;
+  let m;
+  while ((m = camelRe.exec(content)) !== null) {
+    const token = m[1];
+    const start = m.index!;
+    const end = start + token.length;
+    const before = content.slice(Math.max(0, start - 20), start);
+    const after = content.slice(end);
+    // Invocation: preceded by a verb, followed by a clause boundary or call syntax.
+    if (/(?:^|\s)(?:use|run|call|invoke)\s*$/i.test(before) &&
+        /^(?:\s*(?:$|[.,;(:]|(?:when|before|after|to|with|for|on|in|if|unless|whenever)\b))/i.test(after)) {
+      return true;
+    }
+    // Keyword-adjacent: camelCase beside a tool/command keyword.
+    if (/^(?:\s*(?:tool|command|subcommand)\b)/i.test(after) ||
+        /(?:tool|command|subcommand)\s*$/i.test(before)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function referencesAgentSpecificTool(content: string): boolean {
+  if (typeof content !== "string" || content.length === 0) return false;
+  return TOOL_REFERENCE_CI.test(content) || hasCapitalisedToolName(content) || hasCamelCaseToolName(content);
+}
+
+export interface ToolScopeWithholdInputs {
+  content: string;
+  sourceConnector?: string;
+  procedureSteps?: ReadonlyArray<{ intent?: string; expectedOutcome?: string; toolCall?: { kind?: string } }>;
+}
+
+export function withholdToolScopedFromSharedNamespace({
+  content,
+  sourceConnector,
+  procedureSteps,
+}: ToolScopeWithholdInputs): boolean {
+  if (typeof sourceConnector !== "string" || sourceConnector.trim().length === 0) return false;
+  if (referencesAgentSpecificTool(content)) return true;
+  if (
+    procedureSteps?.some((s) => {
+      const kind = s.toolCall?.kind;
+      if (typeof kind === "string" && kind.trim().length > 0) return true;
+      const stepText = [s.intent, s.expectedOutcome]
+        .filter((t): t is string => typeof t === "string" && t.length > 0)
+        .join(" ");
+      return stepText.length > 0 && referencesAgentSpecificTool(stepText);
+    })
+  ) {
+    return true;
+  }
+  return false;
+}
+
+export interface GlobalFactPromotionInputs {
+  scope: string | null | undefined;
+  content: string;
+  sourceConnector?: string;
+  procedureSteps?: ReadonlyArray<{ toolCall?: { kind?: string } }>;
+}
+
+export function shouldPromoteGlobalFactToShared(inputs: GlobalFactPromotionInputs): boolean {
+  if (inputs.scope !== "global") return false;
+  return !withholdToolScopedFromSharedNamespace({
+    content: inputs.content,
+    sourceConnector: inputs.sourceConnector,
+    procedureSteps: inputs.procedureSteps,
+  });
+}

package/src/types.ts

@@ -23,15 +23,12 @@ export type ExtractionPassSource = "base" | "proactive";
 /**
  * Scope classification for extracted facts (issue #XXX).
  *
- * - `"project"` — knowledge specific to one codebase: file paths, environment
- *   configs, deployment details, project-specific workarounds, team/stakeholder
- *   info tied to one project.
- * - `"global"` — knowledge that applies across projects: core framework bugs,
- *   library behavior, API patterns, user preferences, tool configurations,
- *   general coding patterns, infrastructure knowledge.
+ * - `"project"` — one codebase (paths, env configs, deployment, stakeholders);
+ *   also tool/command or CLI-flag instructions tied to one agent.
+ * - `"global"` — across projects: framework bugs, library/API behavior,
+ *   user preferences, coding patterns, infrastructure.
  *
- * Default is `"project"` when a coding context is active, `"global"` when no
- * coding context is present.
+ * Default is `"project"` with a coding context active, else `"global"`.
  */
 export type MemoryScope = "project" | "global";
 export type SlotMismatchMode = "error" | "warn" | "silent";
@@ -3333,6 +3330,8 @@ export interface ExtractionResult {
   extractionFailure?: string;
   /** Coarse class used by the retry/backoff + circuit-breaker layer (extraction hot loop). */
   extractionFailureClass?: ExtractionFailureClass;
+  /** Trusted source connector resolved over boundedTurns; persisted verbatim by the orchestrator so it is not recomputed (#2183). */
+  sourceConnector?: string;
 }
 
 export interface EntityMention {