@massu/core 1.2.1 → 1.4.0-soak.0

package/src/detect/adapters/swift-swiftui.ts

@@ -0,0 +1,171 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: SwiftUI AST adapter.
+ *
+ * Extracts:
+ *   - api_client_class: identifier ending in `API` (e.g. `HedgeAPI`)
+ *   - biometric_policy: `LAPolicy.deviceOwnerAuthenticationWithBiometrics` etc.
+ *   - navigation_pattern: 'NavigationStack' | 'NavigationView' | null
+ *
+ * Tree-sitter Swift grammar quirks: the `tree-sitter-swift` grammar names some
+ * nodes differently from python/typescript. We use simpler, more permissive
+ * S-expressions that fall back to capture-text matching where needed.
+ */
+
+import { Parser } from 'web-tree-sitter';
+import type { CodebaseAdapter, AdapterResult, DetectionSignals, Provenance, SourceFile } from './types.ts';
+import { runQuery, InvalidQueryError } from './query-helpers.ts';
+import { loadGrammar } from './tree-sitter-loader.ts';
+import { isParsableSource, MAX_AST_FILE_BYTES } from './parse-guard.ts';
+
+// ============================================================
+// Queries
+// ============================================================
+
+/**
+ * Identifier that looks like an API client class. Captures any uppercase-led
+ * identifier ending in `API`. Predicate filtering is done in JS — Swift's
+ * grammar doesn't surface a clean class-instantiation pattern uniformly.
+ */
+const API_CLASS_QUERY = `
+(simple_identifier) @ident
+`;
+
+/**
+ * `.deviceOwnerAuthentication` / `.deviceOwnerAuthenticationWithBiometrics`
+ * member access. Captures the property name.
+ */
+const POLICY_QUERY = `
+(navigation_expression
+  suffix: (navigation_suffix
+    (simple_identifier) @policy_name))
+`;
+
+/**
+ * NavigationStack / NavigationView usage. Captures any reference to either
+ * symbol.
+ */
+const NAV_QUERY = `
+(simple_identifier) @nav_ident
+`;
+
+// ============================================================
+// Adapter
+// ============================================================
+
+const POLICY_NAMES = new Set([
+  'deviceOwnerAuthentication',
+  'deviceOwnerAuthenticationWithBiometrics',
+]);
+
+export const swiftSwiftUiAdapter: CodebaseAdapter = {
+  id: 'swift-swiftui',
+  languages: ['swift'],
+
+  matches(signals: DetectionSignals): boolean {
+    // Swift signal: presence of Package.swift, *.xcodeproj, or Sources/ dir
+    if (signals.presentFiles.has('Package.swift')) return true;
+    for (const dir of signals.presentDirs) {
+      if (dir.endsWith('.xcodeproj') || dir.endsWith('.xcworkspace')) return true;
+      if (dir === 'Sources') return true;
+    }
+    for (const file of signals.presentFiles) {
+      if (file.endsWith('.swift')) return true;
+    }
+    return false;
+  },
+
+  async introspect(files: SourceFile[], _rootDir: string): Promise<AdapterResult> {
+    if (files.length === 0) {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    let language;
+    try {
+      language = await loadGrammar('swift');
+    } catch {
+      return { conventions: {}, provenance: [], confidence: 'none' };
+    }
+
+    const parser = new Parser();
+    parser.setLanguage(language);
+
+    const apiClasses = new Map<string, { line: number; file: string }>();
+    const policies = new Map<string, { line: number; file: string }>();
+    const navs = new Map<string, { line: number; file: string }>();
+
+    try {
+      for (const file of files) {
+        const skip = isParsableSource(file.content, file.size);
+        if (skip) {
+          process.stderr.write(
+            `[massu/ast] WARN: swift-swiftui skipping ${file.path}: ${skip.reason} (${skip.detail}). Cap=${MAX_AST_FILE_BYTES}. (Phase 3.5 mitigation)\n`,
+          );
+          continue;
+        }
+        try {
+          // API class names: filter via JS regex on the captured identifier
+          for (const hit of runQuery(parser, file.content, API_CLASS_QUERY, 'swift-api-class', file.path)) {
+            const ident = hit.captures.ident;
+            if (ident && /^[A-Z][A-Za-z0-9_]*API$/.test(ident) && !apiClasses.has(ident)) {
+              apiClasses.set(ident, { line: hit.line, file: file.path });
+            }
+          }
+          // Biometric policy
+          for (const hit of runQuery(parser, file.content, POLICY_QUERY, 'swift-biometric-policy', file.path)) {
+            const name = hit.captures.policy_name;
+            if (name && POLICY_NAMES.has(name) && !policies.has(name)) {
+              policies.set(name, { line: hit.line, file: file.path });
+            }
+          }
+          // Navigation
+          for (const hit of runQuery(parser, file.content, NAV_QUERY, 'swift-navigation', file.path)) {
+            const ident = hit.captures.nav_ident;
+            if ((ident === 'NavigationStack' || ident === 'NavigationView') && !navs.has(ident)) {
+              navs.set(ident, { line: hit.line, file: file.path });
+            }
+          }
+        } catch (e) {
+          if (e instanceof InvalidQueryError) throw e;
+          continue;
+        }
+      }
+    } finally {
+      try { parser.delete(); } catch { /* ignore */ }
+    }
+
+    const conventions: Record<string, unknown> = {};
+    const provenance: Provenance[] = [];
+
+    if (apiClasses.size > 0) {
+      const [name, { line, file }] = apiClasses.entries().next().value as [string, { line: number; file: string }];
+      conventions.api_client_class = name;
+      provenance.push({ field: 'api_client_class', sourceFile: file, line, query: 'swift-api-class' });
+    }
+    if (policies.size > 0) {
+      const [name, { line, file }] = policies.entries().next().value as [string, { line: number; file: string }];
+      conventions.biometric_policy = name;
+      provenance.push({ field: 'biometric_policy', sourceFile: file, line, query: 'swift-biometric-policy' });
+    }
+    if (navs.size > 0) {
+      const [name, { line, file }] = navs.entries().next().value as [string, { line: number; file: string }];
+      conventions.navigation_pattern = name;
+      provenance.push({ field: 'navigation_pattern', sourceFile: file, line, query: 'swift-navigation' });
+    }
+
+    let confidence: AdapterResult['confidence'];
+    if (Object.keys(conventions).length === 0) {
+      confidence = 'none';
+    } else if (apiClasses.size === 1 && policies.size <= 1) {
+      confidence = 'high';
+    } else if (apiClasses.size > 1) {
+      confidence = 'low';
+    } else {
+      confidence = 'medium';
+    }
+
+    return { conventions, provenance, confidence };
+  },
+};

package/src/detect/adapters/tree-sitter-loader.ts

@@ -0,0 +1,348 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: Tree-sitter WASM grammar loader (Strategy A).
+ *
+ * Strategy A — locked at Phase 0 (`docs/internal/2026-04-26-ast-lsp-spec.md`
+ * §1, §8): grammars are NOT bundled in the npm tarball. The loader downloads
+ * each requested grammar at first use from a pinned URL, verifies SHA-256
+ * against a hardcoded manifest, caches under `~/.massu/wasm-cache/`.
+ *
+ * Security model (Phase 3.5 #3):
+ *   - SHA-256 manifest hardcoded HERE — never network-fetched.
+ *   - Mismatch → throw `GrammarSHAMismatchError`. NO silent fallback.
+ *   - Atomic cache write: `<lang>-<sha>.wasm.tmp.<pid>` → rename → final.
+ *   - Offline + no-cache → throw `GrammarUnavailableError` so the runner can
+ *     translate to a regex-fallback path with a stderr note.
+ *
+ * Phase 1 ships the CODE PATH; the actual SHA-256 values for each grammar
+ * URL are placeholders pending Phase 9 release-prep (`curl <url> | shasum
+ * -a 256`). The placeholder string is intentionally non-empty so the
+ * verification logic exercises the comparison branch in tests.
+ */
+
+import { createHash } from 'crypto';
+import {
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+  lstatSync,
+  chmodSync,
+} from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { Language, Parser } from 'web-tree-sitter';
+import type { TreeSitterLanguage } from './types.ts';
+
+// ============================================================
+// Typed errors
+// ============================================================
+
+/** Thrown when downloaded WASM SHA-256 doesn't match the hardcoded manifest. */
+export class GrammarSHAMismatchError extends Error {
+  public readonly language: TreeSitterLanguage;
+  public readonly expected: string;
+  public readonly actual: string;
+  constructor(language: TreeSitterLanguage, expected: string, actual: string) {
+    super(
+      `[tree-sitter-loader] SHA-256 mismatch for grammar "${language}". ` +
+        `Expected ${expected}, got ${actual}. ` +
+        `REFUSING to load — see Phase 3.5 audit attack vector #3.`,
+    );
+    this.name = 'GrammarSHAMismatchError';
+    this.language = language;
+    this.expected = expected;
+    this.actual = actual;
+  }
+}
+
+/** Thrown when a grammar can't be obtained: download failed AND cache empty. */
+export class GrammarUnavailableError extends Error {
+  public readonly language: TreeSitterLanguage;
+  public readonly cause?: unknown;
+  constructor(language: TreeSitterLanguage, cause?: unknown) {
+    const causeMsg =
+      cause instanceof Error ? cause.message : cause ? String(cause) : 'no cached grammar and download failed';
+    super(
+      `[tree-sitter-loader] Grammar for "${language}" is unavailable: ${causeMsg}. ` +
+        `Falling back to regex introspection for files in ${language}.`,
+    );
+    this.name = 'GrammarUnavailableError';
+    this.language = language;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Thrown when the cache path resolves to a symlink (or any non-regular
+ * file). Pre-creating a symlink at the expected cache path is a known
+ * vector for redirecting reads/writes elsewhere on the filesystem.
+ * (Phase 3.5 finding #3 — symlink attack on cache dir.)
+ */
+export class GrammarCacheSymlinkError extends Error {
+  public readonly cachePath: string;
+  constructor(cachePath: string) {
+    super(
+      `[tree-sitter-loader] Refusing to load grammar — cache path "${cachePath}" is a symlink ` +
+        `or non-regular file. (Phase 3.5 finding #3 — symlink attack vector.)`,
+    );
+    this.name = 'GrammarCacheSymlinkError';
+    this.cachePath = cachePath;
+  }
+}
+
+/**
+ * Thrown when a manifest URL is not HTTPS. The manifest is hardcoded in
+ * source, but defense in depth: any future edit that introduces an http://
+ * URL is rejected at load time, not at code review.
+ * (Phase 3.5 finding #3 — MITM on download.)
+ */
+export class GrammarUrlNotHttpsError extends Error {
+  public readonly url: string;
+  constructor(url: string) {
+    super(
+      `[tree-sitter-loader] Refusing to download grammar from non-HTTPS URL: ${url}. ` +
+        `Only https:// URLs are accepted. (Phase 3.5 finding #3.)`,
+    );
+    this.name = 'GrammarUrlNotHttpsError';
+    this.url = url;
+  }
+}
+
+// ============================================================
+// Pinned manifest
+// ============================================================
+
+interface ManifestEntry {
+  url: string;
+  sha256: string;
+  version: string;
+}
+
+/**
+ * Hardcoded grammar manifest. Source-code-resident; tampering requires a
+ * release.
+ *
+ * Source: `tree-sitter-wasms` npm package (https://npm.im/tree-sitter-wasms)
+ * — pre-built WASM binaries for Tree-sitter language parsers. NOT added as
+ * a dependency (per plan §Phase 0 ban on bundling); fetched from unpkg at
+ * first use. The individual `tree-sitter-<lang>` packages on npm do NOT
+ * ship `.wasm` files, only C source + native .node prebuilds — confirmed
+ * by inspecting unpkg `?meta` listings during Phase 9 release-prep.
+ *
+ * SHA-256 hashes computed 2026-04-28 via:
+ *   curl -fsSL <url> | shasum -a 256
+ *
+ * The verification code path is exercised in `tree-sitter-loader.test.ts`
+ * by injecting test manifest entries that intentionally mismatch.
+ */
+export const GRAMMAR_MANIFEST: Partial<Record<TreeSitterLanguage, ManifestEntry>> = {
+  python: {
+    url: 'https://unpkg.com/tree-sitter-wasms@0.1.13/out/tree-sitter-python.wasm',
+    sha256: '9056d0fb0c337810d019fae350e8167786119da98f0f282aceae7ab89ee8253b',
+    version: '0.1.13',
+  },
+  typescript: {
+    url: 'https://unpkg.com/tree-sitter-wasms@0.1.13/out/tree-sitter-typescript.wasm',
+    sha256: '8515404dceed38e1ed86aa34b09fcf3379fff1b4ff9dd3967bcd6d1eb5ac3d8f',
+    version: '0.1.13',
+  },
+  javascript: {
+    url: 'https://unpkg.com/tree-sitter-wasms@0.1.13/out/tree-sitter-javascript.wasm',
+    sha256: '63812b9e275d26851264734868d27a1656bd44a2ef6eb3e85e6b03728c595ab5',
+    version: '0.1.13',
+  },
+  swift: {
+    url: 'https://unpkg.com/tree-sitter-wasms@0.1.13/out/tree-sitter-swift.wasm',
+    sha256: '41c4fdb2249a3aa6d87eed0d383081ff09725c2248b4977043a43825980ffcc7',
+    version: '0.1.13',
+  },
+};
+
+// ============================================================
+// Cache + Parser init
+// ============================================================
+
+function getCacheDir(): string {
+  return process.env.MASSU_WASM_CACHE_DIR ?? join(homedir(), '.massu', 'wasm-cache');
+}
+
+function getCachedPath(language: TreeSitterLanguage, sha: string): string {
+  return join(getCacheDir(), `${language}-${sha}.wasm`);
+}
+
+function sha256(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+let parserInitPromise: Promise<void> | null = null;
+
+/**
+ * `Parser.init()` is async and must be called once before any `new Parser()`.
+ * This function is idempotent — repeated calls return the same promise.
+ *
+ * Test harnesses can mock this by stubbing `Parser.init`.
+ */
+export async function ensureParserInitialized(): Promise<void> {
+  if (parserInitPromise) return parserInitPromise;
+  parserInitPromise = Parser.init();
+  return parserInitPromise;
+}
+
+// ============================================================
+// Loader (the main entry point)
+// ============================================================
+
+interface LoaderOptions {
+  /**
+   * Test-injection: override the manifest entry for a language. Production
+   * callers leave this undefined; tests use it to exercise SHA-mismatch and
+   * download-failure paths.
+   */
+  manifestOverride?: Partial<Record<TreeSitterLanguage, ManifestEntry>>;
+  /**
+   * Test-injection: override the fetch implementation. Defaults to global
+   * `fetch`. Tests pass a mock that returns a fixed body or throws.
+   */
+  fetchImpl?: (url: string) => Promise<{ ok: boolean; arrayBuffer: () => Promise<ArrayBuffer>; status?: number }>;
+}
+
+const loadedGrammars = new Map<TreeSitterLanguage, Language>();
+
+/**
+ * Lazy-load a Tree-sitter grammar. Only fetches/caches the grammar for
+ * `language`; other languages are unaffected.
+ *
+ * Order:
+ *   1. In-memory cache hit → return.
+ *   2. Disk cache hit + SHA verify pass → load from disk.
+ *   3. Disk cache hit + SHA mismatch → throw GrammarSHAMismatchError.
+ *   4. Cache miss → fetch from pinned URL → SHA verify → atomic write → load.
+ *   5. Fetch fails AND no cache → throw GrammarUnavailableError.
+ */
+export async function loadGrammar(
+  language: TreeSitterLanguage,
+  options: LoaderOptions = {},
+): Promise<Language> {
+  await ensureParserInitialized();
+
+  const cached = loadedGrammars.get(language);
+  if (cached) return cached;
+
+  const manifest = options.manifestOverride?.[language] ?? GRAMMAR_MANIFEST[language];
+  if (!manifest) {
+    throw new GrammarUnavailableError(
+      language,
+      new Error(`No manifest entry for language "${language}". v1 supports: ${Object.keys(GRAMMAR_MANIFEST).join(', ')}.`),
+    );
+  }
+
+  const cachePath = getCachedPath(language, manifest.sha256);
+
+  // 2/3: disk cache check. Use lstatSync (NOT statSync) so a symlink at
+  // the cache path is detected and rejected — never followed.
+  // (Phase 3.5 finding #3 — symlink attack on cache dir.)
+  let cacheLstat;
+  try {
+    cacheLstat = lstatSync(cachePath);
+  } catch {
+    cacheLstat = null;
+  }
+  if (cacheLstat) {
+    if (cacheLstat.isSymbolicLink() || !cacheLstat.isFile()) {
+      throw new GrammarCacheSymlinkError(cachePath);
+    }
+    let bytes: Uint8Array;
+    try {
+      bytes = readFileSync(cachePath);
+    } catch (e) {
+      // Treat read failure as cache miss; fall through to download.
+      bytes = new Uint8Array(0);
+    }
+    if (bytes.byteLength > 0) {
+      const actualSha = sha256(bytes);
+      if (actualSha !== manifest.sha256) {
+        // Refuse to load. Don't silently re-download — that would mask
+        // tampering of the on-disk cache.
+        throw new GrammarSHAMismatchError(language, manifest.sha256, actualSha);
+      }
+      const lang = await Language.load(bytes);
+      loadedGrammars.set(language, lang);
+      return lang;
+    }
+  }
+
+  // 4/5: download. Defense in depth: refuse non-HTTPS URLs.
+  if (!/^https:\/\//i.test(manifest.url)) {
+    throw new GrammarUrlNotHttpsError(manifest.url);
+  }
+
+  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as LoaderOptions['fetchImpl']);
+  if (!fetchImpl) {
+    throw new GrammarUnavailableError(
+      language,
+      new Error('No fetch implementation available (Node < 18?)'),
+    );
+  }
+
+  let body: Uint8Array;
+  try {
+    const res = await fetchImpl(manifest.url);
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status ?? 'unknown'} from ${manifest.url}`);
+    }
+    body = new Uint8Array(await res.arrayBuffer());
+  } catch (e) {
+    throw new GrammarUnavailableError(language, e);
+  }
+
+  const downloadedSha = sha256(body);
+  if (downloadedSha !== manifest.sha256) {
+    throw new GrammarSHAMismatchError(language, manifest.sha256, downloadedSha);
+  }
+
+  // Atomic cache write. Always create the dir first.
+  // Mode 0o700 on the dir + 0o600 on files — owner-only access prevents
+  // local information disclosure of cached grammars.
+  // (Phase 3.5 finding #3 — file-mode hardening.)
+  try {
+    mkdirSync(dirname(cachePath), { recursive: true, mode: 0o700 });
+    try { chmodSync(dirname(cachePath), 0o700); } catch { /* best effort */ }
+    const tmpPath = `${cachePath}.tmp.${process.pid}`;
+    writeFileSync(tmpPath, body, { mode: 0o600 });
+    try { chmodSync(tmpPath, 0o600); } catch { /* best effort */ }
+    try {
+      renameSync(tmpPath, cachePath);
+      try { chmodSync(cachePath, 0o600); } catch { /* best effort */ }
+    } catch (e) {
+      // Try to clean up the tmp file on rename failure
+      try {
+        unlinkSync(tmpPath);
+      } catch {
+        /* ignore */
+      }
+      throw e;
+    }
+  } catch (e) {
+    // Cache write failure is non-fatal — we still have `body` in memory and
+    // can load directly. Log to stderr per VR-USER-ERROR-MESSAGES style.
+    console.error(
+      `[tree-sitter-loader] cache write failed for ${language}: ${e instanceof Error ? e.message : String(e)} — loading directly from memory.`,
+    );
+  }
+
+  const lang = await Language.load(body);
+  loadedGrammars.set(language, lang);
+  return lang;
+}
+
+/**
+ * Test-only: clear in-memory loaded grammar cache. Disk cache persists.
+ * Production code never needs this; the in-memory map lives for the process.
+ */
+export function __resetLoadedGrammars(): void {
+  loadedGrammars.clear();
+}

package/src/detect/adapters/types.ts

@@ -0,0 +1,174 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 1: AST Adapter contract types.
+ *
+ * Lives at `packages/core/src/detect/adapters/types.ts` per the spec doc
+ * (`docs/internal/2026-04-26-ast-lsp-spec.md` §2). All types are local —
+ * NONE re-exported from `web-tree-sitter`.
+ *
+ * Adapter authors import from this module only; the runner (`runner.ts`)
+ * orchestrates execution and the loader (`tree-sitter-loader.ts`) handles
+ * grammar acquisition.
+ *
+ * Per-field confidence is enforced (NOT per-adapter): a single weak field
+ * MUST NOT poison the rest. The runner consumes `confidence` per-adapter for
+ * the moment, but the merge rule reads each `conventions[field]` against the
+ * provenance trail to decide what survives.
+ */
+
+// ============================================================
+// Languages enumerated for the AST adapter set (Phase 1 + 3c)
+// ============================================================
+
+/**
+ * Closed-set of Tree-sitter grammars massu ships first-party adapters for.
+ *
+ * Note: this is a string-literal union, NOT re-exported from `web-tree-sitter`
+ * (which exposes `Language` as a class, not a name list). Phase 1 ships
+ * adapters for python/typescript/javascript/swift only — the remaining
+ * languages are reserved for Plan 3c.
+ */
+export type TreeSitterLanguage =
+  | 'python'
+  | 'typescript'
+  | 'javascript'
+  | 'swift'
+  | 'rust'
+  | 'go'
+  | 'ruby'
+  | 'php'
+  | 'java'
+  | 'kotlin'
+  | 'elixir'
+  | 'erlang'
+  | 'csharp'
+  | 'cpp'
+  | 'haskell'
+  | 'ocaml';
+
+// ============================================================
+// Inputs to adapter dispatch
+// ============================================================
+
+/**
+ * Read-only signal bundle the runner builds BEFORE adapter dispatch.
+ *
+ * Adapters consume signals to answer `matches()` cheaply (no file IO inside
+ * `matches()` — that's why the bundle is built up-front).
+ */
+export interface DetectionSignals {
+  /** Parsed `package.json` (root or first workspace) — undefined if absent. */
+  packageJson?: Record<string, unknown>;
+  /** Parsed `pyproject.toml` — undefined if absent. */
+  pyprojectToml?: Record<string, unknown>;
+  /** Raw `Gemfile` text — undefined if absent. */
+  gemfile?: string;
+  /** Parsed `Cargo.toml` — undefined if absent. */
+  cargoToml?: Record<string, unknown>;
+  /** Raw `go.mod` text — undefined if absent. */
+  goMod?: string;
+  /** Set of present directory names directly under the project root (one level). */
+  presentDirs: Set<string>;
+  /** Set of present file basenames directly under the project root (one level). */
+  presentFiles: Set<string>;
+}
+
+/**
+ * A sampled source file the runner hands to the adapter.
+ *
+ * `content` is pre-read; adapters MUST NOT re-read from disk inside
+ * `introspect()`. `size` is in bytes (pre-read length).
+ */
+export interface SourceFile {
+  path: string;
+  content: string;
+  language: TreeSitterLanguage;
+  size: number;
+}
+
+// ============================================================
+// Adapter contract
+// ============================================================
+
+/**
+ * Trail entry produced for every captured field — the user can audit
+ * `detected.<adapter>._provenance` to see exactly which file/line/query
+ * produced a value.
+ */
+export interface Provenance {
+  field: string;
+  sourceFile: string;
+  line: number;
+  query: string;
+}
+
+export interface AdapterResult {
+  /**
+   * Becomes `detected.<adapter.id>` in `massu.config.yaml`. Field names are
+   * adapter-defined; values are `unknown` so adapters can return strings,
+   * arrays, or nested records as needed.
+   */
+  conventions: Record<string, unknown>;
+  /**
+   * Per-field provenance trail. The runner writes this to
+   * `detected.<adapter.id>._provenance` so a downstream auditor can verify
+   * any extracted value.
+   */
+  provenance: Provenance[];
+  /**
+   * 'high'  : single canonical match, query produced exactly one result
+   * 'medium': multiple matches, all agree
+   * 'low'   : multiple matches with disagreement (still emitted, with warning)
+   * 'none'  : no matches, timed out, or threw — fields are dropped
+   */
+  confidence: 'high' | 'medium' | 'low' | 'none';
+}
+
+export interface CodebaseAdapter {
+  /** Stable adapter id, e.g. "python-fastapi". Becomes `detected.<id>` block. */
+  id: string;
+  /** Languages this adapter consumes. Used by the runner to skip work. */
+  languages: TreeSitterLanguage[];
+  /**
+   * Cheap signal check — must NOT do file IO. Returns true if any signal
+   * suggests this adapter should run.
+   */
+  matches(signals: DetectionSignals): boolean;
+  /**
+   * Sample N files (already read by the runner), run AST queries, return
+   * extracted conventions. May throw — the runner isolates failures.
+   */
+  introspect(files: SourceFile[], rootDir: string): Promise<AdapterResult>;
+}
+
+// ============================================================
+// Runner output
+// ============================================================
+
+/**
+ * The runner's output: per-adapter id → its conventions block (with the
+ * `_provenance` map merged in). The introspector then folds this into the
+ * `detected.<adapter.id>` namespace alongside the existing
+ * `detected.python` / `detected.swift` / `detected.typescript` regex blocks.
+ */
+export interface MergedAdapterOutput {
+  /** Per-adapter id → resolved conventions. */
+  byAdapter: Record<string, AdapterResolved>;
+  /** Adapters that were skipped (didn't match) for diagnostic logging. */
+  skipped: string[];
+  /** Adapters that threw during introspect — runner isolates these. */
+  errored: Array<{ adapterId: string; error: string }>;
+}
+
+/**
+ * Resolved-and-merged form of an `AdapterResult`. Provenance is folded into
+ * `_provenance` (key per field, value = `path:line :: query`).
+ */
+export interface AdapterResolved {
+  conventions: Record<string, unknown>;
+  /** field-name -> "relativePath:line :: queryName". Empty when no fields. */
+  _provenance: Record<string, string>;
+  confidence: 'high' | 'medium' | 'low' | 'none';
+}