@mrclrchtr/supi-code-intelligence 2.0.6 → 2.1.0

package/node_modules/@mrclrchtr/supi-tree-sitter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "2.0.6",
+  "version": "2.1.0",
   "description": "SuPi Tree-sitter extension — structural AST analysis for pi",
   "license": "MIT",
   "repository": {
@@ -35,8 +35,8 @@
   ],
   "dependencies": {
     "web-tree-sitter": "^0.26.8",
-    "@mrclrchtr/supi-code-runtime": "2.0.6",
-    "@mrclrchtr/supi-core": "2.0.6"
+    "@mrclrchtr/supi-code-runtime": "2.1.0",
+    "@mrclrchtr/supi-core": "2.1.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-intelligence",
-  "version": "2.0.6",
+  "version": "2.1.0",
   "description": "SuPi Code Intelligence extension — architecture briefs, caller/callee analysis, impact assessment, and pattern search for pi",
   "license": "MIT",
   "repository": {
@@ -34,10 +34,10 @@
   ],
   "dependencies": {
     "ts-pattern": "^5.9.0",
-    "@mrclrchtr/supi-code-runtime": "2.0.6",
-    "@mrclrchtr/supi-core": "2.0.6",
-    "@mrclrchtr/supi-lsp": "2.0.6",
-    "@mrclrchtr/supi-tree-sitter": "2.0.6"
+    "@mrclrchtr/supi-code-runtime": "2.1.0",
+    "@mrclrchtr/supi-core": "2.1.0",
+    "@mrclrchtr/supi-lsp": "2.1.0",
+    "@mrclrchtr/supi-tree-sitter": "2.1.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",

package/src/analysis/evidence.ts

@@ -1,3 +1,16 @@
+/**
+ * Evidence-list helpers — the shared leaf utility for bounded tool-evidence
+ * collections with explicit completeness metadata.
+ *
+ * These helpers (types, builders, disclosure renderers) are consumed by both
+ * the `analysis/` layer (brief/reference/git formatters that produce markdown
+ * fragments) and the `tool/` layer (markdown/TUI renderers and tool-result
+ * assembly). They live here, at the lower layer, so `analysis/` never imports
+ * upward into `tool/`. The tool-result *assembly* (`assemble*` functions and
+ * details types) lives in `src/tool/result/`; this module is the shared
+ * evidence-list primitive beneath it.
+ */
+
 export type EvidencePartialReason = "timeout" | "safety-limit" | "interrupted" | "provider-limited";
 
 export interface EvidenceListMetadata {

package/src/analysis/search/pattern.ts

@@ -64,7 +64,7 @@ export function isStructuredPatternKind(kind: string | undefined): kind is Struc
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: enumeration-interrupted, cap, timeout, and error branches are each necessary
 export async function getStructuredPatternMatches(
   params: StructuredPatternParams,
-  scopePath: string,
+  scopePath: string | readonly string[],
   cwd: string,
   relScope: string,
   structural: StructuralSubstrate,
@@ -143,7 +143,10 @@ interface FileEnumeration {
  * Enumerate all tree-sitter-supported source files in scopePath using rg --files.
  * Returns null if ripgrep is not available.
  */
-function enumerateSourceFiles(scopePath: string, cwd: string): FileEnumeration | null {
+function enumerateSourceFiles(
+  scopePath: string | readonly string[],
+  cwd: string,
+): FileEnumeration | null {
   const extensions = getSupportedExtensions();
   // Strip leading dots — ripgrep -g expects ".ext" without the dot prefix
   const globPattern = `*.{${Array.from(extensions)
@@ -151,18 +154,14 @@ function enumerateSourceFiles(scopePath: string, cwd: string): FileEnumeration |
     .join(",")}}`;
 
   try {
-    const output = execFileSync("rg", ["--files", "-g", globPattern, scopePath], {
+    const output = execFileSync("rg", ["--files", "-g", globPattern, ...scopePathArgs(scopePath)], {
       encoding: "utf-8",
       cwd,
       timeout: 5000,
       stdio: ["pipe", "pipe", "pipe"],
     });
     return {
-      files: output
-        .split("\n")
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0)
-        .sort((a, b) => a.localeCompare(b)),
+      files: normalizeEnumeratedFiles(output),
       interrupted: false,
     };
   } catch (err: unknown) {
@@ -174,11 +173,7 @@ function enumerateSourceFiles(scopePath: string, cwd: string): FileEnumeration |
       const stdout = typeof err.stdout === "string" ? err.stdout : "";
       const wasKilled = (err as { killed?: boolean }).killed === true;
       return {
-        files: stdout
-          .split("\n")
-          .map((line) => line.trim())
-          .filter((line) => line.length > 0)
-          .sort((a, b) => a.localeCompare(b)),
+        files: normalizeEnumeratedFiles(stdout),
         interrupted: wasKilled,
       };
     }
@@ -186,6 +181,22 @@ function enumerateSourceFiles(scopePath: string, cwd: string): FileEnumeration |
   }
 }
 
+function scopePathArgs(scopePath: string | readonly string[]): string[] {
+  const paths = Array.isArray(scopePath) ? scopePath : [scopePath];
+  return paths.length > 0 ? [...paths] : ["."];
+}
+
+function normalizeEnumeratedFiles(output: string): string[] {
+  return [
+    ...new Set(
+      output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0),
+    ),
+  ].sort((a, b) => a.localeCompare(b));
+}
+
 // biome-ignore lint/complexity/useMaxParams: helper takes explicit collection inputs to avoid intermediate objects in the hot path
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: kind-specific tree-sitter matching is clearest as one helper
 async function collectMatchesForFile(

package/src/analysis/search/ripgrep.ts

@@ -47,6 +47,11 @@ export function isInProjectPath(filePath: string, cwd: string): boolean {
 /** Result of resolving a user-provided `scope` value to an absolute path. */
 export type ScopeResolution = { kind: "ok"; path: string } | { kind: "error"; reason: string };
 
+/** Result of resolving a code_find `scope` value to one or more absolute paths. */
+export type ScopeSetResolution =
+  | { kind: "ok"; paths: string[]; display: string | null }
+  | { kind: "error"; reason: string };
+
 /**
  * Resolve a `scope` value to an absolute path using pi scope semantics:
  * - strip leading `@`
@@ -61,6 +66,55 @@ export function resolveScope(scope: string | undefined, cwd: string): ScopeResol
       reason: `Scope accepts a single directory or file path, not multiple: \`${scope}\``,
     };
   }
+  return resolveSingleScope(scope, cwd);
+}
+
+/**
+ * Resolve a code_find scope input to one or more absolute paths.
+ *
+ * `code_find` is intentionally more flexible than other code-intelligence tools:
+ * it accepts `scope: ["docs", "packages"]` and also splits delimiter-separated
+ * strings such as `"docs packages"` only when no exact path by that name exists.
+ */
+export function resolveScopeSet(
+  scope: string | readonly string[] | undefined,
+  cwd: string,
+): ScopeSetResolution {
+  if (scope === undefined) {
+    return { kind: "ok", paths: [cwd], display: null };
+  }
+
+  const labels = typeof scope === "string" ? splitScopeString(scope, cwd) : [...scope];
+  if (labels.length === 0) {
+    return { kind: "error", reason: "Scope must include at least one directory or file path." };
+  }
+
+  const resolved: Array<{ label: string; path: string }> = [];
+  for (const label of labels) {
+    const trimmed = label.trim();
+    if (!trimmed) {
+      return { kind: "error", reason: "Scope must not include empty path entries." };
+    }
+    const single = resolveSingleScope(trimmed, cwd);
+    if (single.kind === "error") return single;
+    resolved.push({ label: trimmed, path: single.path });
+  }
+
+  const byPath = new Map<string, string>();
+  for (const entry of resolved) {
+    if (!byPath.has(entry.path)) byPath.set(entry.path, entry.label);
+  }
+  const paths = [...byPath.keys()];
+  const uniqueLabels = paths.map((p) => byPath.get(p) ?? p);
+
+  return {
+    kind: "ok",
+    paths,
+    display: uniqueLabels.length > 0 ? uniqueLabels.join(", ") : null,
+  };
+}
+
+function resolveSingleScope(scope: string, cwd: string): ScopeResolution {
   const resolved = normalizePath(scope, cwd);
   if (!existsSync(resolved)) {
     return { kind: "error", reason: `Scope path not found: \`${scope}\`` };
@@ -68,6 +122,20 @@ export function resolveScope(scope: string | undefined, cwd: string): ScopeResol
   return { kind: "ok", path: resolved };
 }
 
+function splitScopeString(scope: string, cwd: string): string[] {
+  const trimmed = scope.trim();
+  if (!trimmed) return [];
+
+  const exact = resolveSingleScope(trimmed, cwd);
+  if (exact.kind === "ok") return [trimmed];
+
+  const parts = trimmed
+    .split(/[,;\s]+/)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  return parts.length > 1 ? parts : [trimmed];
+}
+
 /** Escape regex special characters. */
 export function escapeRegex(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -152,7 +220,7 @@ export class RipgrepAbortedError extends Error {
  */
 export async function runRipgrep(
   pattern: string,
-  scopePath: string,
+  scopePath: string | readonly string[],
   cwd: string,
   opts?: RipgrepOptions,
 ): Promise<RgMatch[]> {
@@ -166,7 +234,7 @@ export async function runRipgrep(
  */
 export async function runRipgrepDetailed(
   pattern: string,
-  scopePath: string,
+  scopePath: string | readonly string[],
   cwd: string,
   opts?: RipgrepOptions,
 ): Promise<RipgrepRunResult> {
@@ -195,16 +263,16 @@ export async function runRipgrepDetailed(
       };
     case "ok":
     case "nomatch":
-      return { matches: parseRgJson(proc.stdout, filter) };
+      return { matches: dedupeMatches(parseRgJson(proc.stdout, filter)) };
     case "timeout":
       // Timeout: yield any partial stdout matches with no error surfaced — an
       // improvement over the prior execFileSync path, which discarded partial
       // output on timeout (the timeout error lacked a `status`, so the old
       // handleRipgrepError returned an empty match set).
-      return { matches: proc.stdout ? parseRgJson(proc.stdout, filter) : [] };
+      return { matches: proc.stdout ? dedupeMatches(parseRgJson(proc.stdout, filter)) : [] };
     case "error":
       return {
-        matches: proc.stdout ? parseRgJson(proc.stdout, filter) : [],
+        matches: proc.stdout ? dedupeMatches(parseRgJson(proc.stdout, filter)) : [],
         ...(proc.stderr.trim() ? { error: proc.stderr.trim() } : {}),
       };
   }
@@ -212,7 +280,7 @@ export async function runRipgrepDetailed(
 
 function buildRipgrepArgs(
   pattern: string,
-  scopePath: string,
+  scopePath: string | readonly string[],
   opts?: { maxMatches?: number; contextLines?: number; literal?: boolean },
 ): string[] {
   const args = ["--json", "-m", String(opts?.maxMatches ?? 30)];
@@ -222,10 +290,15 @@ function buildRipgrepArgs(
   if (opts?.literal) {
     args.push("-F");
   }
-  args.push("-e", pattern, scopePath);
+  args.push("-e", pattern, ...normalizeScopePathArgs(scopePath));
   return args;
 }
 
+function normalizeScopePathArgs(scopePath: string | readonly string[]): string[] {
+  const paths = Array.isArray(scopePath) ? scopePath : [scopePath];
+  return paths.length > 0 ? [...paths] : ["."];
+}
+
 /** Discriminated result of a single ripgrep process run (see {@link runRgProcess}). */
 type RgProcessResult =
   | { kind: "ok"; stdout: string; stderr: string; status: number }
@@ -432,6 +505,18 @@ function parseRgJson(output: string, filterLowSignal: boolean): RgMatch[] {
   return matches;
 }
 
+function dedupeMatches(matches: RgMatch[]): RgMatch[] {
+  const seen = new Set<string>();
+  const deduped: RgMatch[] = [];
+  for (const match of matches) {
+    const key = `${match.file}\u0000${match.line}\u0000${match.text}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(match);
+  }
+  return deduped;
+}
+
 /**
  * Minimal interface for a reference-like object with a URI and range start.
  * Used by {@link filterOutDeclaration} to avoid coupling to a specific LspRef type.

package/src/extension.ts

@@ -38,7 +38,7 @@ export default function codeIntelligenceExtension(
   const tsState = createTsAdapterState();
 
   // ── Substrate wiring ──────────────────────────────────────────────
-  registerLspSettings();
+  registerLspSettings(pi);
   registerLspSessionLifecycle(pi, lspState);
   registerLspAwareToolOverrides(pi, lspState);
   registerDiagnosticInjectionHandlers(pi, lspState);

package/src/session/capability-adapter.ts

@@ -0,0 +1,218 @@
+/**
+ * Capability adapter — injected dependency for WorkspaceCodeIntelligenceSession.
+ *
+ * Encapsulates provider access and readiness so the session target
+ * workflow can be tested with an in-memory adapter. Two adapters
+ * (production and test) justify the seam.
+ *
+ * @mrclrchtr/supi-code-intelligence — internal, not exported via api.ts
+ */
+
+import type { SemanticProvider, StructuralProvider } from "@mrclrchtr/supi-code-runtime/api";
+import { getDefaultWorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
+import type { SessionLspServiceState } from "@mrclrchtr/supi-lsp/api";
+import {
+  type CodeProvider,
+  type CodeProviderState,
+  getCodeProviderState,
+} from "../analysis/provider.ts";
+import { ensureSemanticReadiness } from "../analysis/readiness.ts";
+
+// ── Interface ─────────────────────────────────────────────────────────
+
+/**
+ * Readiness scope for semantic provider gating.
+ * `workspace` waits for all servers; `file` waits for a specific file's server.
+ */
+export type ReadinessScope = { kind: "workspace" } | { kind: "file"; file: string };
+
+/** Outcome of a readiness wait. */
+export type ReadinessOutcome =
+  | { kind: "ready" }
+  | { kind: "timeout" }
+  | { kind: "unavailable"; reason: string };
+
+/**
+ * Injected capability adapter.
+ *
+ * Production adapter reads the global workspace runtime. Test adapter
+ * provides semantic/structural providers in memory without global state.
+ */
+export interface CapabilityAdapter {
+  /** Get the composite code provider state for a workspace. */
+  getProviderState(cwd: string): CodeProviderState;
+
+  /** Convenience: get the ready composite provider, or null. */
+  getProvider(cwd: string): CodeProvider | null;
+
+  /** Get the raw semantic provider, or null. */
+  getSemanticProvider(cwd: string): SemanticProvider | null;
+
+  /** Get the raw structural provider, or null. */
+  getStructuralProvider(cwd: string): StructuralProvider | null;
+
+  /**
+   * Wait for semantic (LSP) readiness. Returns a typed outcome so
+   * the target workflow can decide whether to proceed, return a
+   * timeout note, or return an unavailable result.
+   */
+  ensureSemanticReadiness(cwd: string, scope: ReadinessScope): Promise<ReadinessOutcome>;
+}
+
+// ── Production adapter ────────────────────────────────────────────────
+
+/**
+ * Production capability adapter that reads from the global workspace
+ * runtime. Used in the real pi session.
+ */
+export class WorkspaceCapabilityAdapter implements CapabilityAdapter {
+  getProviderState(cwd: string): CodeProviderState {
+    return getCodeProviderState(cwd);
+  }
+
+  getProvider(cwd: string): CodeProvider | null {
+    const state = this.getProviderState(cwd);
+    return state.kind === "ready" ? state.provider : null;
+  }
+
+  getSemanticProvider(cwd: string): SemanticProvider | null {
+    const runtime = getDefaultWorkspaceRuntime();
+    const ws = runtime.getWorkspace(cwd);
+    if (
+      (ws.semantic.state.kind === "ready" || ws.semantic.state.kind === "pending") &&
+      ws.semantic.provider !== null
+    ) {
+      return ws.semantic.provider as SemanticProvider;
+    }
+    return null;
+  }
+
+  getStructuralProvider(cwd: string): StructuralProvider | null {
+    const runtime = getDefaultWorkspaceRuntime();
+    const ws = runtime.getWorkspace(cwd);
+    if (ws.structural.state.kind === "ready" && ws.structural.provider !== null) {
+      return ws.structural.provider as StructuralProvider;
+    }
+    return null;
+  }
+
+  async ensureSemanticReadiness(cwd: string, scope: ReadinessScope): Promise<ReadinessOutcome> {
+    const result = await ensureSemanticReadiness(cwd, scope);
+    return result;
+  }
+
+  /** Convenience: LSP service state for impact/health consumers still using it directly. */
+  getLspService(cwd: string): SessionLspServiceState {
+    const state = this.getProviderState(cwd);
+    return state.kind === "ready"
+      ? state.lspService
+      : { kind: "unavailable" as const, reason: "No provider" };
+  }
+}
+
+// ── Test adapter ──────────────────────────────────────────────────────
+
+/**
+ * In-memory capability adapter for tests.
+ *
+ * Pass explicit providers and readiness outcomes without touching
+ * the global workspace runtime.
+ */
+export class TestCapabilityAdapter implements CapabilityAdapter {
+  readonly #semantic: SemanticProvider | null;
+  readonly #structural: StructuralProvider | null;
+  readonly #readiness: ReadinessOutcome;
+  readonly #lspService: SessionLspServiceState;
+
+  constructor(options: {
+    semantic?: SemanticProvider | null;
+    structural?: StructuralProvider | null;
+    readiness?: ReadinessOutcome;
+    lspService?: SessionLspServiceState;
+  }) {
+    this.#semantic = options.semantic ?? null;
+    this.#structural = options.structural ?? null;
+    this.#readiness = options.readiness ?? { kind: "ready" };
+    this.#lspService = options.lspService ?? {
+      kind: "unavailable" as const,
+      reason: "no test LSP",
+    };
+  }
+
+  getProviderState(_cwd: string): CodeProviderState {
+    if (!this.#semantic && !this.#structural) {
+      return { kind: "unavailable", reason: "No providers in test adapter" };
+    }
+    return {
+      kind: "ready",
+      provider: this.getProvider(_cwd) as CodeProvider,
+      lspService: this.#lspService,
+    };
+  }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: adapter maps many provider methods; splitting would degrade readability
+  getProvider(_cwd: string): CodeProvider | null {
+    if (!this.#semantic && !this.#structural) return null;
+    return {
+      // Semantic pass-through
+      references: this.#semantic?.references
+        ? (...args: Parameters<SemanticProvider["references"]>) =>
+            this.#semantic?.references?.(...args)
+        : async () => null,
+      implementation: this.#semantic?.implementation
+        ? (...args) => this.#semantic?.implementation?.(...args)
+        : async () => null,
+      documentSymbols: this.#semantic?.documentSymbols
+        ? (...args) => this.#semantic?.documentSymbols?.(...args)
+        : async () => [],
+      workspaceSymbols: this.#semantic?.workspaceSymbols
+        ? (...args) => this.#semantic?.workspaceSymbols?.(...args)
+        : async () => [],
+      hover: this.#semantic?.hover ? (...args) => this.#semantic?.hover?.(...args) : undefined,
+      definition: this.#semantic?.definition
+        ? (...args) => this.#semantic?.definition?.(...args)
+        : undefined,
+      codeActions: this.#semantic?.codeActions
+        ? (...args) => this.#semantic?.codeActions?.(...args)
+        : undefined,
+      codeActionTitles: this.#semantic?.codeActionTitles
+        ? (...args) => this.#semantic?.codeActionTitles?.(...args)
+        : undefined,
+      rename: this.#semantic?.rename ? (...args) => this.#semantic?.rename?.(...args) : undefined,
+      refactor: this.#semantic?.refactor
+        ? (...args) => this.#semantic?.refactor?.(...args)
+        : undefined,
+      // Structural pass-through
+      calleesAt: this.#structural?.calleesAt
+        ? (...args) => this.#structural?.calleesAt?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+      exports: this.#structural?.exports
+        ? (...args) => this.#structural?.exports?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+      outline: this.#structural?.outline
+        ? (...args) => this.#structural?.outline?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+      imports: this.#structural?.imports
+        ? (...args) => this.#structural?.imports?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+      nodeAt: this.#structural?.nodeAt
+        ? (...args) => this.#structural?.nodeAt?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+      callSites: this.#structural?.callSites
+        ? (...args) => this.#structural?.callSites?.(...args)
+        : async () => ({ kind: "unavailable" as const, message: "no test structural" }),
+    } as CodeProvider;
+  }
+
+  getSemanticProvider(_cwd: string): SemanticProvider | null {
+    return this.#semantic;
+  }
+
+  getStructuralProvider(_cwd: string): StructuralProvider | null {
+    return this.#structural;
+  }
+
+  async ensureSemanticReadiness(_cwd: string, _scope: ReadinessScope): Promise<ReadinessOutcome> {
+    return this.#readiness;
+  }
+}

package/src/session/session.ts

@@ -24,6 +24,7 @@ import type { LspRuntimeController } from "@mrclrchtr/supi-lsp/api";
 import { CoverageWarningState } from "../analysis/coverage/coverage-warnings.ts";
 import type { CodeProvider } from "../analysis/provider.ts";
 import { getCodeProvider } from "../analysis/provider.ts";
+import { type CapabilityAdapter, WorkspaceCapabilityAdapter } from "./capability-adapter.ts";
 import { getPlan, type RefactorPlan, removePlan, storePlan } from "./refactor-plans.ts";
 import {
   getWorkflowTarget,
@@ -33,11 +34,18 @@ import {
   type TargetRegistrationOutput,
   type TargetStoreEntry,
 } from "./target-store.ts";
+import {
+  resolveTargetWorkflow,
+  type TargetWorkflowInput,
+  type TargetWorkflowOutcome,
+  type TargetWorkflowPolicy,
+} from "./target-workflow.ts";
 
 // ── Re-export types consumed by callers ───────────────────────────────
 
 export type { CoverageWarningState } from "../analysis/coverage/coverage-warnings.ts";
 export type { CodeProvider, CodeProviderState } from "../analysis/provider.ts";
+export type { CapabilityAdapter } from "./capability-adapter.ts";
 export type { RefactorPlan } from "./refactor-plans.ts";
 export type {
   TargetLookupResult,
@@ -45,6 +53,11 @@ export type {
   TargetRegistrationOutput,
   TargetStoreEntry,
 } from "./target-store.ts";
+export type {
+  TargetWorkflowInput,
+  TargetWorkflowOutcome,
+  TargetWorkflowPolicy,
+} from "./target-workflow.ts";
 
 // ── Target ID expansion result ────────────────────────────────────────
 
@@ -74,6 +87,9 @@ export class WorkspaceCodeIntelligenceSession {
   /** Canonical workspace directory for this session. */
   readonly cwd: string;
 
+  /** Injected capability adapter — two adapters (production/test) justify the seam. */
+  readonly #capability: CapabilityAdapter;
+
   /** Whether the hidden architecture overview has been injected. */
   hasInjectedOverview = false;
 
@@ -100,8 +116,30 @@ export class WorkspaceCodeIntelligenceSession {
    */
   tsController: import("@mrclrchtr/supi-tree-sitter/api").TreeSitterRuntimeController | null = null;
 
-  constructor(cwd: string) {
+  constructor(cwd: string, capability?: CapabilityAdapter) {
     this.cwd = cwd;
+    this.#capability = capability ?? new WorkspaceCapabilityAdapter();
+  }
+
+  // ── Target workflow (deep seam) ───────────────────────────────────
+
+  /**
+   * Resolve target input into an immutable resolved target.
+   *
+   * This is the deep module interface. Tool executors call this instead
+   * of `expandTargetId` or direct `resolveTarget`/`resolveAnchoredSymbolTarget`
+   * calls. Returns typed outcomes — no markdown, no mutated params.
+   */
+  async resolveTarget(
+    input: TargetWorkflowInput,
+    policy: TargetWorkflowPolicy,
+  ): Promise<TargetWorkflowOutcome> {
+    return resolveTargetWorkflow(input, policy, {
+      cwd: this.cwd,
+      capability: this.#capability,
+      lookupTargetId: (id) => this.lookupTargetId(id),
+      registerTarget: (inp) => this.registerTarget(inp),
+    });
   }
 
   // ── Provider access ───────────────────────────────────────────────