@elkindev/dbgraph 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,2692 @@
+import { SpawnSyncOptions, SpawnSyncReturns } from 'node:child_process';
+
+/**
+ * Logger port — design §7.2.
+ * Core uses the injected Logger; never console.log (dbgraph-conventions).
+ * A no-op default logger is exported so functions can take an optional logger
+ * without null checks.
+ */
+interface Logger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+/** No-op default logger — used when the caller does not inject one. */
+declare const noopLogger: Logger;
+
+/**
+ * open-connections — composition-root utility (phase-5-mcp-server task 2.1).
+ *
+ * Relocated from src/cli/config/open-connections.ts to a NEUTRAL composition
+ * layer so both the CLI and MCP adapter can consume it through the barrel
+ * (src/index.ts) without either side importing the other's layer.
+ *
+ * Design Decision 4 (phase-5-mcp-server): infra MAY import adapter/store
+ * factories — it is the composition seam. Both CLI and MCP import the barrel;
+ * the barrel re-exports this module.
+ *
+ * ADR-004: imports from the barrel (../../index.js) for adapter/store factories;
+ * config helpers imported from ./config/ (src/infra/config/) — NEVER from
+ * src/cli/** (that direction violates the cli↔mcp decoupling, ADR-004).
+ * Security: resolved secrets are NEVER logged; the resolved config is ephemeral.
+ */
+
+type AdapterAndStore = {
+    adapter: Awaited<ReturnType<typeof createSqliteSchemaAdapter>> | Awaited<ReturnType<typeof createMssqlSchemaAdapter>> | Awaited<ReturnType<typeof createPgSchemaAdapter>> | Awaited<ReturnType<typeof createMysqlSchemaAdapter>> | Awaited<ReturnType<typeof createMongodbSchemaAdapter>>;
+    store: Awaited<ReturnType<typeof createSqliteGraphStore>>;
+};
+/** Injectable seams for {@link openConnections} (phase-9.5c, design D2). */
+interface OpenConnectionsDeps {
+    /**
+     * SEA detection override — default reads `node:sea`.isSea via createRequire
+     * (NOT a static node:sea import). Inside a SEA binary this is true → the local
+     * store flips to `node:sqlite`; off-SEA it is false → default better-sqlite3.
+     */
+    readonly isSea?: () => boolean;
+}
+/**
+ * Reads dbgraph.config.json from projectRoot, resolves ${env:VAR} secrets,
+ * creates the appropriate schema adapter, ensures .dbgraph/ exists, and
+ * opens the SQLite graph store.
+ *
+ * Callers are responsible for calling adapter.close() and store.close() in a
+ * finally block after use.
+ *
+ * @param projectRoot - The directory containing dbgraph.config.json.
+ * @param logger      - Optional Logger for strategy-selection transparency.
+ *                      Defaults to noopLogger (back-compat — existing callers
+ *                      that do not pass a logger are unaffected).
+ *
+ * Throws ConfigError if:
+ *   - dbgraph.config.json is missing or malformed
+ *   - any ${env:VAR} reference is unresolved
+ */
+declare function openConnections(projectRoot: string, logger?: Logger, deps?: OpenConnectionsDeps): Promise<AdapterAndStore>;
+
+/**
+ * Node kinds, graph nodes, indexing levels, and per-type level configuration.
+ * Design §4.1 — engine-agnostic domain types.
+ */
+type NodeKind = 'database' | 'schema' | 'table' | 'column' | 'constraint' | 'index' | 'view' | 'procedure' | 'function' | 'trigger' | 'sequence' | 'collection' | 'field';
+/** Runtime-accessible tuple of all NodeKind values (used for validation and tests). */
+declare const NODE_KINDS: readonly NodeKind[];
+type IndexLevel = 'off' | 'metadata' | 'full';
+/** Runtime-accessible tuple of all IndexLevel values. */
+declare const INDEX_LEVELS: readonly IndexLevel[];
+/**
+ * Per-object-type level configuration.
+ * ADR-003 defaults: triggers full; procedures/functions metadata; statistics/sampling off.
+ */
+interface ObjectTypeLevels {
+    tables: IndexLevel;
+    columns: IndexLevel;
+    constraints: IndexLevel;
+    indexes: IndexLevel;
+    views: IndexLevel;
+    procedures: IndexLevel;
+    functions: IndexLevel;
+    triggers: IndexLevel;
+    sequences: IndexLevel;
+    collections: IndexLevel;
+    fields: IndexLevel;
+    statistics: IndexLevel;
+    sampling: IndexLevel;
+}
+/**
+ * Opaque per-kind JSON payload. Adapters may add engine-specific keys.
+ * Typed accessor views (TablePayload, etc.) provide compile-time ergonomics.
+ */
+type NodePayload = Readonly<Record<string, unknown>>;
+interface TablePayload {
+    rowCountEstimate?: number;
+    comment?: string;
+}
+interface ColumnPayload {
+    dataType: string;
+    nullable: boolean;
+    default?: string | null;
+    ordinal: number;
+    comment?: string;
+}
+interface ConstraintPayload {
+    type: 'PK' | 'FK' | 'UNIQUE' | 'CHECK';
+    definition?: string;
+    columns: readonly string[];
+}
+interface IndexPayload {
+    unique: boolean;
+    columns: readonly string[];
+    method?: string;
+}
+interface RoutinePayload {
+    signature?: string;
+    returns?: string;
+    body?: string;
+    hasDynamicSql: boolean;
+    comment?: string;
+}
+interface TriggerPayload {
+    timing?: 'BEFORE' | 'AFTER' | 'INSTEAD OF';
+    events: readonly ('INSERT' | 'UPDATE' | 'DELETE')[];
+    body?: string;
+    hasDynamicSql: boolean;
+    comment?: string;
+}
+/**
+ * Accessor view for a 'field' node (MongoDB sampled field).
+ * Mirrors ColumnPayload structurally so inferReferences (which reads payload.dataType
+ * as a string) consumes a 'field' node identically to a 'column' node (Design §D1).
+ * dataType is a union string like 'int|string' (sorted) — NOT a types[] array.
+ */
+interface FieldPayload {
+    dataType: string;
+    frequency: number;
+    nullable?: boolean;
+}
+interface GraphNode {
+    readonly id: string;
+    readonly kind: NodeKind;
+    readonly schema: string | null;
+    readonly name: string;
+    readonly qname: string;
+    readonly level: IndexLevel;
+    readonly missing: boolean;
+    readonly excluded: boolean;
+    readonly bodyHash: string | null;
+    readonly payload: NodePayload;
+}
+
+/**
+ * Edge kinds, confidence classification, edge attributes, and graph edges.
+ * Design §4.2 — engine-agnostic domain types.
+ */
+type EdgeKind = 'references' | 'depends_on' | 'reads_from' | 'writes_to' | 'fires_on' | 'has_column' | 'has_index' | 'has_constraint' | 'in_index' | 'inferred_reference';
+/** Runtime-accessible tuple of all EdgeKind values. */
+declare const EDGE_KINDS: readonly EdgeKind[];
+type EdgeConfidence = 'declared' | 'parsed' | 'inferred';
+/** Runtime-accessible tuple of all EdgeConfidence values. */
+declare const EDGE_CONFIDENCE_VALUES: readonly EdgeConfidence[];
+interface EdgeAttrs {
+    readonly srcColumn?: string;
+    readonly dstColumn?: string;
+    readonly event?: 'INSERT' | 'UPDATE' | 'DELETE';
+    readonly aggregate?: boolean;
+    readonly ordinal?: number;
+    readonly constraintName?: string;
+}
+interface GraphEdge {
+    readonly id: string;
+    readonly kind: EdgeKind;
+    readonly src: string;
+    readonly dst: string;
+    readonly confidence: EdgeConfidence;
+    readonly score: number | null;
+    readonly attrs: EdgeAttrs;
+}
+
+/**
+ * RawCatalog — the durable adapter→core contract.
+ * Design §4.5 — what every engine adapter produces and feeds to normalizeCatalog.
+ * This file imports NOTHING from adapters, drivers, mcp, or cli (ADR-004).
+ */
+
+interface RawCatalog {
+    readonly engine: string;
+    readonly engineVersion?: string;
+    readonly schemas: readonly string[];
+    readonly objects: readonly RawObject[];
+}
+interface RawField {
+    readonly name: string;
+    readonly dataType: string;
+    readonly frequency: number;
+    readonly nullable?: boolean;
+}
+interface RawObject {
+    readonly kind: NodeKind;
+    readonly schema: string | null;
+    readonly name: string;
+    readonly columns?: readonly RawColumn[];
+    readonly constraints?: readonly RawConstraint[];
+    readonly indexes?: readonly RawIndex[];
+    readonly fields?: readonly RawField[];
+    readonly signature?: string;
+    readonly returns?: string;
+    readonly body?: string;
+    readonly hasDynamicSql?: boolean;
+    readonly trigger?: RawTriggerInfo;
+    readonly dependencies?: readonly RawDependency[];
+    readonly comment?: string;
+    readonly extra?: Readonly<Record<string, unknown>>;
+}
+interface RawColumn {
+    readonly name: string;
+    readonly dataType: string;
+    readonly nullable: boolean;
+    readonly default?: string | null;
+    readonly ordinal: number;
+    readonly comment?: string;
+}
+interface RawConstraint {
+    readonly name: string;
+    readonly type: 'PK' | 'FK' | 'UNIQUE' | 'CHECK';
+    readonly columns: readonly string[];
+    readonly references?: {
+        schema: string | null;
+        table: string;
+        columns: readonly string[];
+    };
+    readonly definition?: string;
+}
+interface RawIndex {
+    readonly name: string;
+    readonly unique: boolean;
+    readonly columns: readonly string[];
+    readonly method?: string;
+}
+interface RawTriggerInfo {
+    readonly timing: 'BEFORE' | 'AFTER' | 'INSTEAD OF';
+    readonly events: readonly ('INSERT' | 'UPDATE' | 'DELETE')[];
+    readonly table: {
+        schema: string | null;
+        name: string;
+    };
+}
+interface RawDependency {
+    readonly target: {
+        schema: string | null;
+        name: string;
+        kind?: NodeKind;
+    };
+    readonly access: 'read' | 'write';
+    readonly confidence: 'declared' | 'parsed';
+}
+
+/**
+ * CapabilityMatrix, ExtractionScope, and DEFAULT_LEVELS.
+ * Design §4.3 — what an engine supports and the normalizer's second argument.
+ * No adapter, driver, mcp, or cli imports (ADR-004).
+ */
+
+interface CapabilityMatrix {
+    readonly engine: string;
+    readonly supported: ReadonlySet<NodeKind>;
+    readonly defaultLevels: ObjectTypeLevels;
+    readonly supportsBodies: boolean;
+    readonly supportsDependencyHints: boolean;
+}
+interface ExtractionScope {
+    readonly levels: ObjectTypeLevels;
+    readonly include?: readonly string[];
+    readonly exclude?: readonly string[];
+    /**
+     * Opt-in gate for structural inference (US-008).
+     * When `true`, the normalizer calls `inferReferences` after step 4c.
+     * When absent or `false` (the default), inference is skipped and the normalizer
+     * output is byte-identical to pre-Phase-9a behavior (the four shipped SQL engines
+     * stay unaffected). Design D3.
+     */
+    readonly inferRelationships?: boolean;
+}
+
+/**
+ * NormalizedGraph, NormalizationResult, OmittedKindInfo, and StubInfo.
+ * Design §4.6 — the output contract of normalizeCatalog.
+ * No adapter, driver, mcp, or cli imports (ADR-004).
+ */
+
+interface NormalizedGraph {
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+}
+interface StubInfo {
+    readonly id: string;
+    readonly qname: string;
+    readonly kind: NodeKind;
+    readonly reason: 'missing' | 'excluded';
+    readonly referencedBy: string;
+}
+/**
+ * Records an object type that was omitted because its level is 'off' in the scope.
+ * US-003 / graph-model spec "off level is an absence, not silence":
+ * "a queryable absence reason is representable".
+ */
+interface OmittedKindInfo {
+    /** The object kind that was configured off. */
+    readonly kind: NodeKind;
+    /** Human-readable reason: always "not indexed by configuration" (US-003 spec wording). */
+    readonly reason: string;
+}
+interface NormalizationResult {
+    readonly graph: NormalizedGraph;
+    readonly stubs: readonly StubInfo[];
+    readonly warnings: readonly string[];
+    /** US-003 / W-1: off-level kinds with queryable absence reason (spec: "not indexed by configuration"). */
+    readonly omitted: readonly OmittedKindInfo[];
+}
+
+/**
+ * GraphStore port — the driven port for graph persistence.
+ * Design §11 — async signatures so the port is the seam for node:sqlite / bun:sqlite (ADR-005).
+ * The SQLite adapter wraps synchronous calls in resolved Promises (zero runtime cost).
+ * This file imports NOTHING from adapters, drivers, mcp, or cli (ADR-004).
+ */
+
+interface UpsertResult {
+    readonly nodes: number;
+    readonly edges: number;
+}
+interface SearchHit {
+    readonly id: string;
+    readonly kind: NodeKind;
+    readonly qname: string;
+    readonly column: 'qname' | 'comment' | 'body';
+    readonly score: number;
+}
+interface SnapshotRecord {
+    readonly id: string;
+    readonly takenAt: string;
+    readonly engine: string;
+    readonly engineVersion?: string;
+    readonly fingerprint: string;
+    readonly counts: Readonly<Record<string, number>>;
+}
+/** One row in the snapshot_objects manifest (phase-4-cli-config Batch F). */
+interface SnapshotObjectRow {
+    readonly snapshotId: string;
+    readonly nodeId: string;
+    readonly kind: string;
+    readonly qname: string;
+    readonly bodyHash: string | null;
+}
+interface NeighborQuery {
+    readonly nodeId: string;
+    readonly kinds?: readonly EdgeKind[];
+}
+interface NeighborGroups {
+    readonly [kind: string]: {
+        readonly out: readonly {
+            node: GraphNode;
+            edge: GraphEdge;
+        }[];
+        readonly in: readonly {
+            node: GraphNode;
+            edge: GraphEdge;
+        }[];
+    };
+}
+interface ImpactQuery {
+    readonly nodeId: string;
+    readonly depth?: number;
+}
+interface ImpactChain {
+    readonly nodes: readonly string[];
+    readonly edges: readonly EdgeKind[];
+}
+interface ImpactResult {
+    readonly readImpact: readonly ImpactChain[];
+    readonly writeImpact: readonly ImpactChain[];
+    readonly truncated: boolean;
+    readonly dynamicSqlWarning: boolean;
+}
+interface PathQuery {
+    readonly from: string;
+    readonly to: string;
+    readonly allowInferred?: boolean;
+}
+interface JoinHop {
+    readonly fromTable: string;
+    readonly toTable: string;
+    readonly joinColumns: readonly {
+        from: string;
+        to: string;
+    }[];
+}
+interface PathResult {
+    readonly found: boolean;
+    readonly hops?: readonly JoinHop[];
+    readonly inferred?: boolean;
+    readonly nearest?: {
+        from: readonly string[];
+        to: readonly string[];
+    };
+}
+interface SearchQuery {
+    readonly term: string;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+interface GraphStore {
+    close(): Promise<void>;
+    schemaVersion(): Promise<number>;
+    upsertGraph(graph: NormalizedGraph): Promise<UpsertResult>;
+    deleteNodes(ids: readonly string[]): Promise<number>;
+    getNode(id: string): Promise<GraphNode | null>;
+    getNodesByKind(kind: NodeKind): Promise<readonly GraphNode[]>;
+    getNodeByQName(kind: NodeKind, qname: string): Promise<GraphNode | null>;
+    getEdgesFrom(nodeId: string, kinds?: readonly EdgeKind[]): Promise<readonly GraphEdge[]>;
+    getEdgesTo(nodeId: string, kinds?: readonly EdgeKind[]): Promise<readonly GraphEdge[]>;
+    searchFts(query: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        hits: readonly SearchHit[];
+        total: number;
+    }>;
+    putSnapshot(s: SnapshotRecord): Promise<void>;
+    listSnapshots(): Promise<readonly SnapshotRecord[]>;
+    /** Returns the snapshot_objects manifest for the given snapshot (phase-4-cli-config Batch F). */
+    getSnapshotObjects(snapshotId: string): Promise<readonly SnapshotObjectRow[]>;
+    getMeta(key: string): Promise<string | null>;
+    setMeta(key: string, value: string): Promise<void>;
+}
+
+/**
+ * SchemaAdapter port — the driving port for source-database schema extraction.
+ * Design §1 "SchemaAdapter port shape" — async lifecycle symmetric with GraphStore.
+ * This file imports NOTHING from adapters, drivers, mcp, or cli (ADR-004).
+ * The concrete join to a driver lives in src/adapters/engines/<engine>/.
+ *
+ * US-026 (first concrete adapter), US-031 (read-only by construction),
+ * US-009 (per-engine fingerprint).
+ */
+
+/**
+ * Configuration for the SQLite schema adapter.
+ * `file` is the path to the source .db file (or ':memory:' for tests).
+ * `driver` selects the driver explicitly; defaults to `better-sqlite3`.
+ * NO silent auto-fallback — design §2 "Driver selection is explicit".
+ */
+interface SqliteAdapterConfig {
+    readonly file: string;
+    readonly driver?: 'better-sqlite3' | 'node:sqlite';
+}
+/**
+ * Configuration for the Microsoft SQL Server schema adapter.
+ * Structural union member — distinguished from SqliteAdapterConfig by the
+ * presence of `server`, `database`, and `authentication` (no `dialect` field
+ * needed; each engine keeps its own factory taking its concrete config type).
+ *
+ * authentication.type 'sql'      — SQL Server authentication (user + password).
+ * authentication.type 'ntlm'     — Windows/NTLM authentication (domain + user + password).
+ * authentication.type 'integrated' — Windows Integrated Security; NO credentials required.
+ *                                    The current OS session identity is used (ADR-006 note:
+ *                                    tedious cannot handle this; the strategy registry will
+ *                                    skip the native strategy and use an external tool instead).
+ *
+ * US-027 (SQL Server adapter), ADR-007 (no new generic config shape).
+ * connectivity-strategies A1.4: integrated member added additively.
+ */
+interface MssqlAdapterConfig {
+    readonly server: string;
+    readonly port?: number;
+    readonly database: string;
+    readonly authentication: {
+        readonly type: 'sql';
+        readonly user: string;
+        readonly password: string;
+    } | {
+        readonly type: 'ntlm';
+        readonly domain: string;
+        readonly user: string;
+        readonly password: string;
+    } | {
+        readonly type: 'integrated';
+    };
+    readonly encrypt?: boolean;
+    readonly trustServerCertificate?: boolean;
+}
+/**
+ * Configuration for the PostgreSQL schema adapter.
+ *
+ * IMPORTANT — union discriminability: These config shapes are NOT discriminable
+ * by structure alone (both PgAdapterConfig and MysqlAdapterConfig carry `host`).
+ * The union is a plain structural union for typing only; runtime dispatch is by
+ * the EXPLICIT config `dialect` field in parse-config.ts / open-connections.ts,
+ * and each engine factory takes its own concrete config type directly.
+ * No `dialect` discriminant is added to the union members.
+ *
+ * `password` MUST be supplied as a `${env:VAR}` reference — never a literal.
+ * `port` defaults to 5432 when omitted.
+ * `schema` is optional: omit to extract all non-system schemas; supply to scope
+ * extraction to a single schema.
+ *
+ * US-028 (PostgreSQL adapter), pg-extraction spec "Connectivity via host/port".
+ */
+interface PgAdapterConfig {
+    readonly host: string;
+    readonly port?: number;
+    readonly database: string;
+    readonly user: string;
+    readonly password: string;
+    readonly ssl?: boolean | {
+        readonly rejectUnauthorized?: boolean;
+    };
+    readonly schema?: string;
+}
+/**
+ * Configuration for the MySQL schema adapter.
+ *
+ * IMPORTANT — union discriminability: Both PgAdapterConfig and MysqlAdapterConfig
+ * carry `host`; the union is intentionally NON-discriminable by structural shape.
+ * Runtime dispatch keys on the EXPLICIT config `dialect` field in parse-config.ts
+ * and open-connections.ts. Each engine factory takes its own concrete config type
+ * directly. No `dialect` discriminant is added to union members.
+ *
+ * `password` MUST be supplied as a `${env:VAR}` reference — never a literal.
+ * `port` defaults to 3306 when omitted.
+ * NO `schema?` field: the connected `database` IS the extraction scope
+ * (schema == database in MySQL — there is no schema-vs-database distinction).
+ *
+ * US-029 (MySQL adapter, Phase 8b), mysql-extraction spec "Connectivity via host/port".
+ */
+interface MysqlAdapterConfig {
+    readonly host: string;
+    readonly port?: number;
+    readonly database: string;
+    readonly user: string;
+    readonly password: string;
+    readonly ssl?: boolean | {
+        readonly rejectUnauthorized?: boolean;
+    };
+}
+/**
+ * Configuration for the MongoDB schema adapter.
+ *
+ * URI-based: the full connection string is carried in `uri` — NO host/port/user/
+ * password/schema decomposition. The password (embedded in the URI) MUST be
+ * supplied as a `${env:VAR}` reference; literals are REJECTED by the parser.
+ *
+ * IMPORTANT — union discriminability: Runtime dispatch keys on the EXPLICIT config
+ * `dialect` field in parse-config.ts / open-connections.ts, NOT on shape.
+ * No `dialect` discriminant is added to union members.
+ *
+ * `database` names the extraction scope (also used as the schema name in the
+ * normalized catalog — schema == database for MongoDB).
+ * `sampleSize` controls how many documents per collection are sampled to infer
+ * field types; defaults to 100 at runtime.
+ * `tls` enables TLS/SSL for the connection when true.
+ *
+ * US-030 (MongoDB adapter, Phase 9b), mongodb-extraction spec
+ * "Connectivity via a URI reference".
+ */
+interface MongodbAdapterConfig {
+    readonly uri: string;
+    readonly database: string;
+    readonly sampleSize?: number;
+    readonly tls?: boolean;
+}
+/**
+ * Union of all engine-specific config shapes.
+ *
+ * This is a STRUCTURAL union for typing only — it is intentionally
+ * NON-discriminable by shape (pg and mysql both carry `host`; sqlite uses `file`;
+ * mssql uses `server`; mongodb uses `uri`). Runtime dispatch is by the EXPLICIT
+ * config `dialect` field in parse-config.ts / open-connections.ts; each engine
+ * factory takes its own concrete config type directly. No `dialect` discriminant
+ * is added to members.
+ *
+ * Future engines add their own member without touching existing members.
+ */
+type SchemaAdapterConfig = SqliteAdapterConfig | MssqlAdapterConfig | PgAdapterConfig | MysqlAdapterConfig | MongodbAdapterConfig;
+/**
+ * The driven port every source-database adapter MUST implement.
+ *
+ * Lifecycle:
+ *   createXxxSchemaAdapter(config) → already-open SchemaAdapter
+ *   extract(scope) / fingerprint()  ← may be called any number of times
+ *   close()                         ← idempotent; a second call MUST NOT throw
+ *
+ * The `open` step is handled by the FACTORY (mirrors createSqliteGraphStore),
+ * so this port exposes no `open()` method.
+ */
+interface SchemaAdapter {
+    /** Stable engine identifier, e.g. 'sqlite', 'mssql', 'pg'. */
+    readonly dialect: string;
+    /**
+     * Truthful capability matrix for this engine.
+     * Declares which NodeKind types are extractable, whether bodies are available,
+     * and whether dependency hints are supported.
+     */
+    readonly capabilities: CapabilityMatrix;
+    /**
+     * Extract the source database's schema into a RawCatalog.
+     * Honours the ExtractionScope levels (off / metadata / full).
+     * Returns a value consumable by normalizeCatalog without any adapter import.
+     */
+    extract(scope: ExtractionScope): Promise<RawCatalog>;
+    /**
+     * Compute a cheap drift fingerprint for the current schema.
+     * MUST change on DDL changes; MUST be stable across data-only changes (US-009).
+     * Issues exactly ONE catalog query — does NOT walk all objects.
+     */
+    fingerprint(): Promise<string>;
+    /**
+     * Release the connection. Idempotent — a second call MUST NOT throw.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * CapabilityProbe port — engine-agnostic capability detection contract.
+ * Design §"probe() is OPTIONAL on the strategy port; per-engine probe in adapters".
+ * Resilient-connectivity Batch 1, task 1.1.
+ *
+ * This file imports ONLY core types. It MUST NOT import any driver,
+ * external-tool, node:child_process, adapter, cli, or mcp symbol (ADR-004).
+ * Concrete probe implementations live under src/adapters/engines/<engine>/probe.ts.
+ *
+ * The probe contract:
+ *   - MUST NOT throw — any detection failure reports as a negative result
+ *   - MUST NOT open a database connection to determine availability
+ *   - MUST NOT issue any write
+ */
+/**
+ * Information about a single CLI tool found (or not found) on PATH.
+ * `version` and `path` are null when the tool is absent or its version is
+ * unparseable from the tool's own output.
+ */
+interface CliToolInfo {
+    /** Stable tool name, e.g. 'sqlcmd', 'psql', 'mysql'. */
+    readonly tool: string;
+    /** Parsed version string, or null if absent or unparseable. */
+    readonly version: string | null;
+    /** Resolved absolute path, or null if not found on PATH. */
+    readonly path: string | null;
+}
+/**
+ * The result of running a capability probe for a given engine.
+ * All fields are non-throwing — unavailability is a false/null/empty value.
+ */
+interface ProbeResult {
+    /** Whether the engine's native driver package is importable (no DB connection attempted). */
+    readonly nativeDriver: boolean;
+    /** Zero or more CLI tools scanned on PATH — one entry per relevant tool for this engine. */
+    readonly cliTools: readonly CliToolInfo[];
+    /** Whether an ODBC driver is present (applicable to mssql; false for other engines). */
+    readonly odbc: boolean;
+}
+/**
+ * The driver port every per-engine capability probe MUST implement.
+ *
+ * Implementations live in src/adapters/engines/<engine>/probe.ts.
+ * This interface is consumed driver-free by:
+ *   - core/present/doctor.ts (content-free report)
+ *   - adapters/engines/mssql/strategies/profiles.ts (resolveProfile)
+ *   - cli/commands/doctor.ts (runDoctor)
+ *
+ * ZERO driver, tool, or node:child_process imports are permitted here.
+ */
+interface CapabilityProbe {
+    /**
+     * Stable engine identifier, e.g. 'mssql', 'pg', 'mysql', 'sqlite'.
+     */
+    readonly engine: string;
+    /**
+     * Run a full capability detection for this engine and return the result.
+     *
+     * MUST resolve — never reject.
+     * MUST NOT open a database connection.
+     * MUST NOT issue any write.
+     * A timed-out or failed detection step MUST be reported as a negative result.
+     */
+    probe(): Promise<ProbeResult>;
+}
+
+/**
+ * ConnectivityStrategy port — engine-agnostic strategy contract for schema extraction.
+ * Design §"ConnectivityStrategy port in core, driver-free (ADR-004)".
+ *
+ * This file imports ONLY core model types (RawCatalog, ExtractionScope) and the Logger
+ * port. It MUST NOT import any driver, external-tool, or node:child_process symbol.
+ * Concrete strategies live under src/adapters/engines/<engine>/strategies/ (ADR-004).
+ *
+ * connectivity-strategies Batch A, task A1.1.
+ */
+
+/**
+ * Result of a strategy's availability probe.
+ * `available: false` when the prerequisite (tool on PATH, dump file, credentials) is absent.
+ * `detail` carries human-readable discovery metadata (version, path, reason).
+ */
+interface DetectResult {
+    readonly available: boolean;
+    /** Optional human-readable detail: tool version, file path, or reason unavailable. */
+    readonly detail?: string;
+}
+/**
+ * Records why a strategy was skipped or failed during selection.
+ * Carried by StrategyExhaustionError to enumerate what was tried and why.
+ */
+interface StrategyAttempt {
+    /** The stable strategy identifier, e.g. 'native-tedious', 'sqlcmd', 'manual-dump'. */
+    readonly id: string;
+    /** Human-readable reason the strategy could not be used. */
+    readonly reason: string;
+}
+/**
+ * The driven port every connectivity strategy MUST implement.
+ *
+ * Lifecycle (per extraction):
+ *   detect()          — is the prerequisite available? (no DB connection opened)
+ *   canConnect()      — cheap SELECT 1 / file-read probe
+ *   runCatalog(scope) — full catalog extraction
+ *   close?()          — release any held resources (idempotent)
+ *
+ * The port is implementable by any engine without changing core (ADR-004).
+ * ZERO driver, tool, or node:child_process imports are permitted here.
+ */
+interface ConnectivityStrategy {
+    /**
+     * Stable identifier for logging and error reporting.
+     * Examples: 'native-tedious', 'sqlcmd', 'manual-dump', 'consented-install'.
+     */
+    readonly id: string;
+    /**
+     * Probe whether the strategy's prerequisite is present on this machine.
+     * MUST NOT open a database connection.
+     * A failed or timed-out probe MUST resolve { available: false }, never reject.
+     */
+    detect(): Promise<DetectResult>;
+    /**
+     * Cheap connectivity probe (SELECT 1 / file readable).
+     * Called only when detect() resolved available: true.
+     * Returns true when the strategy can likely run a full extraction.
+     */
+    canConnect(): Promise<boolean>;
+    /**
+     * Execute the full catalog extraction and return a RawCatalog.
+     * MUST issue ONLY catalog SELECT statements (read-only inviolable, US-031).
+     */
+    runCatalog(scope: ExtractionScope): Promise<RawCatalog>;
+    /**
+     * Run a capability detection for this strategy's engine and return the result.
+     * Optional — existing strategies that omit it remain valid (back-compat).
+     * When present:
+     *   MUST resolve — never reject.
+     *   MUST NOT open a database connection.
+     *   MUST NOT issue any write.
+     * Consumed by adapters/engines/<engine>/strategies/registry.ts (selectStrategy)
+     * and cli/commands/doctor.ts (runDoctor) via the core port shape.
+     * resilient-connectivity Batch 1, task 1.4.
+     */
+    probe?(): Promise<ProbeResult>;
+    /**
+     * Compute a cheap DDL-sensitive fingerprint for the current schema.
+     * Optional. When absent, StrategyBackedSchemaAdapter falls back to a
+     * content-hash over the extracted catalog (if available in the future).
+     * When present, MUST change on DDL changes and be stable on DML (US-009).
+     * Issues exactly ONE catalog query — does NOT walk all objects.
+     */
+    fingerprint?(): Promise<string>;
+    /**
+     * Release any held resources (connection pool, file handle, etc.).
+     * Optional. When present, MUST be idempotent — a second call MUST NOT throw.
+     */
+    close?(): Promise<void>;
+}
+
+/**
+ * Deterministic node/edge ID derivation and canonical qualified-name helpers.
+ * Design §3.4, ADR-008 — IDs are pure functions of semantic identity.
+ * Uses Node's built-in crypto (ADR-007: no new dependencies).
+ * This file imports NOTHING from adapters, drivers, mcp, or cli (ADR-004).
+ */
+/**
+ * Returns the canonical qualified name for a node: case-folded, quote-stripped,
+ * segments joined by '.'. If schema is null, returns just the name.
+ *
+ * @example
+ *   canonicalQName('DBO', 'Orders') // → 'dbo.orders'
+ *   canonicalQName('[dbo]', '[Orders]') // → 'dbo.orders'
+ *   canonicalQName(null, 'my_db') // → 'my_db'
+ */
+declare function canonicalQName(schema: string | null, name: string): string;
+/**
+ * Derives a deterministic node ID from a node kind and its canonical qualified name.
+ * Formula: sha1(kind + ' ' + canonicalQName)
+ *
+ * The kind prefix prevents collisions between e.g. a table and a view sharing
+ * a name in different namespaces. The qname is case-folded by the caller
+ * or via canonicalQName(), so IDs are case-insensitive.
+ *
+ * Stubs reuse the SAME derivation from the referenced qname — a later real
+ * extraction of that object lands on the SAME node ID (idempotent upsert).
+ */
+declare function nodeId(kind: string, qname: string): string;
+/**
+ * Derives a deterministic edge ID from edge kind, source id, destination id,
+ * and a discriminator string that makes parallel edges distinct.
+ *
+ * Discriminator usage:
+ *  - 'references' per-column: 'srcColumn>dstColumn'
+ *  - 'references' aggregated: 'aggregate'
+ *  - 'fires_on':             the event ('INSERT' | 'UPDATE' | 'DELETE')
+ *  - edges that cannot duplicate: '' (empty string)
+ *
+ * Formula: sha1(kind + ' ' + src_id + ' ' + dst_id + ' ' + discriminator)
+ */
+declare function edgeId(kind: string, srcId: string, dstId: string, discriminator: string): string;
+/**
+ * Serializes a value to JSON with recursively sorted object keys so that the
+ * output is byte-identical for the same structural value regardless of the
+ * property insertion order.  Arrays preserve their element order.
+ *
+ * Used in the normalizer to ensure payload/attrs JSON is deterministic (§5.6).
+ */
+declare function stableStringify(value: unknown): string;
+
+/**
+ * normalizeCatalog — the main normalizer entry point.
+ * Design §5 — pipeline: validate → filter → primary nodes → references → stubs → ordering.
+ * Pure function; no I/O. ADR-004: imports only from src/core.
+ * ADR-008: deterministic output (sorted by kind/qname/id; stableStringify for JSON).
+ */
+
+/**
+ * Converts a RawCatalog into a deterministic NormalizationResult.
+ * Design §5.1 pipeline order is strictly followed.
+ */
+declare function normalizeCatalog(raw: RawCatalog, scope: ExtractionScope): NormalizationResult;
+
+/**
+ * Level application (off / metadata / full) and body normalization.
+ * Design §5.4, §5.5 — centralizes level logic so it is applied identically everywhere.
+ * US-003: metadata keeps node+edges but no body; full includes normalized body + FTS.
+ * ADR-005/008: body whitespace normalization ensures bodyHash is stable across environments.
+ * This file imports NOTHING from adapters, drivers, mcp, or cli (ADR-004).
+ */
+
+/**
+ * Normalizes a procedure/trigger body for stable hashing and storage:
+ * 1. Normalizes CRLF → LF.
+ * 2. Trims trailing whitespace on each line.
+ * 3. Drops a trailing newline from the result.
+ *
+ * Does NOT re-format SQL or alter semantics — purely whitespace canonicalization.
+ * Idempotent: normalizing twice yields the same output.
+ */
+declare function normalizeBody(body: string): string;
+/** Result of applying a level to a node's body/comment context. */
+interface LevelResult {
+    /** Normalized body — present only at level='full' and only when body was supplied. */
+    readonly body?: string;
+    /** SHA-1 hash of normalized body (ADR-005); null when body is absent or level≠'full'. */
+    readonly bodyHash: string | null;
+    /** FTS body text: normalized body at 'full', empty string otherwise (US-003). */
+    readonly ftsBody: string;
+    /** Comment/description preserved from input. */
+    readonly comment?: string;
+}
+/**
+ * Applies an indexing level to a node's body/comment context.
+ *
+ * - `off`      → returns null (caller MUST NOT produce a node or FTS row).
+ * - `metadata` → returns LevelResult with no body, null bodyHash, empty ftsBody.
+ * - `full`     → returns LevelResult with normalized body (if supplied), sha1 bodyHash,
+ *                and ftsBody populated with the normalized body for FTS indexing.
+ *
+ * @param input - The level and optional body/comment for the node.
+ * @returns LevelResult for metadata/full, or null for off.
+ */
+declare function applyLevel(input: {
+    level: IndexLevel;
+    body?: string;
+    comment?: string;
+}): LevelResult | null;
+
+/**
+ * getNeighbors — US-013: direct neighbors grouped by edge kind and direction.
+ * Design §6.1 — pure orchestration over the GraphStore port.
+ * ADR-004: imports only core model and ports, never adapters/drivers/mcp/cli.
+ * ADR-008: deterministic output (groups in fixed kind order; neighbors sorted by qname, id).
+ */
+
+/**
+ * Returns all direct neighbors of a node grouped by edge kind and direction.
+ *
+ * - Outbound edges (getEdgesFrom): the neighbour is the edge's `dst`.
+ * - Inbound  edges (getEdgesTo):   the neighbour is the edge's `src`.
+ * - If `q.kinds` is provided, only edges matching those kinds are included.
+ * - Inferred edges appear under their own kind group (`inferred_reference`)
+ *   — they are NOT mixed with declared/parsed edges.
+ * - Deterministic: within each (kind, direction) group, neighbours are sorted
+ *   by (qname, id).
+ */
+declare function getNeighbors(store: GraphStore, q: NeighborQuery): Promise<NeighborGroups>;
+
+/**
+ * getImpact — US-014: depth-limited blast-radius traversal separating read/write impact.
+ * Design §6.2 — BFS over inbound edges, read/write split, visible chains a→b→c,
+ * depth cap + truncation warning, cycle safety (visited set), dynamic-SQL propagation.
+ * ADR-004: imports only core. ADR-008: deterministic output.
+ */
+
+/**
+ * Computes the transitive impact closure of a node as visible dependency chains.
+ *
+ * Algorithm (BFS):
+ * 1. Start from `q.nodeId`; add it to `visited`.
+ * 2. For each frontier node, fetch inbound impact edges (who points AT it).
+ * 3. For each new (unvisited) neighbour create a new chain by extending the
+ *    predecessor chain and enqueue.
+ * 4. Stop expanding when `depth` is reached; set `truncated` if any cut-off
+ *    node had unexpanded inbound edges.
+ * 5. After BFS, classify each chain into readImpact or writeImpact based on
+ *    the last hop's edge kind. A chain may contribute to both if its edges mix
+ *    (the terminal hop decides the bucket).
+ * 6. Set `dynamicSqlWarning` if any node in any surfaced chain has
+ *    `payload.hasDynamicSql === true`.
+ * 7. Sort chains and their nodes deterministically.
+ */
+declare function getImpact(store: GraphStore, q: ImpactQuery): Promise<ImpactResult>;
+
+/**
+ * findJoinPath — US-015: shortest join path over references edges with exact join columns.
+ * Design §6.3 — BFS at table grain over aggregated references edges; per-column edges
+ * supply the exact join columns for each hop. No-route → nearest neighbors suggestion.
+ * ADR-004: imports only core. ADR-008: deterministic (BFS in sorted order; ties by qname/id).
+ */
+
+/**
+ * Finds the shortest join path between two table nodes over `references` edges.
+ *
+ * Algorithm:
+ * 1. BFS over aggregated references edges (attrs.aggregate === true) in both directions.
+ *    Using ONLY aggregated edges avoids traversing per-column edges during BFS;
+ *    they are resolved separately for join columns.
+ * 2. When the target node is found, reconstruct the path from the predecessor map.
+ * 3. For each hop, collect the matching per-column references edges to emit exact join columns.
+ * 4. If `allowInferred` is false (default), skip `inferred_reference` edges.
+ * 5. No route: return `found:false` with the nearest one-hop neighbours of each endpoint.
+ * 6. Same node (from === to): return `found:true` with empty hops array.
+ *
+ * Determinism (ADR-008): BFS explores neighbours in sorted (qname, id) order so the
+ * chosen shortest path is stable across runs. Ties are broken by (qname, id).
+ */
+declare function findJoinPath(store: GraphStore, q: PathQuery): Promise<PathResult>;
+
+/**
+ * search — US-011: full-text search over FTS-indexed graph nodes.
+ * Design §6.4 — delegates to port.searchFts (FTS5 via adapter), with a TS-side
+ * Levenshtein fallback when FTS returns no results (typo tolerance).
+ *
+ * GOLDEN-PINNED constants (ADR-008 — determinism):
+ *   LEVENSHTEIN_THRESHOLD = 2  (max edit distance for fallback match)
+ *   TYPO_CAP              = 5  (max results returned by fallback)
+ *
+ * These MUST NOT be changed without updating goldens and the apply-progress log.
+ *
+ * ADR-004: imports only core. ADR-007: no new dependencies (Levenshtein in-lined here).
+ */
+
+/** Maximum Levenshtein edit distance for a typo-fallback match. */
+declare const LEVENSHTEIN_THRESHOLD: 2;
+/** Maximum number of results returned by the typo-fallback path. */
+declare const TYPO_CAP: 5;
+interface SearchResult {
+    readonly hits: readonly SearchHit[];
+    readonly total: number;
+}
+/**
+ * Searches the graph by full-text term.
+ *
+ * 1. Build an FTS5-compatible prefix query from the term tokens and call
+ *    `store.searchFts`. Results are ranked by BM25 (the adapter handles that).
+ * 2. If FTS returns zero results, run the TS-side Levenshtein fallback:
+ *    - Gather candidate qnames from all non-stub nodes (fetched per-kind via port).
+ *    - Compute Levenshtein distance between the term and each qname's local name.
+ *    - Return up to TYPO_CAP results with distance ≤ LEVENSHTEIN_THRESHOLD,
+ *      sorted by (distance ASC, qname ASC) for determinism (ADR-008).
+ * 3. Propagate `limit`/`offset` to the FTS call; the fallback respects TYPO_CAP.
+ */
+declare function search(store: GraphStore, q: SearchQuery): Promise<SearchResult>;
+
+/**
+ * formatExplore — task 5.1 (phase-4-cli-config).
+ * Spec: cli-config "explore output comes from a pure formatter shared with the MCP tool"
+ * Design: PURE, core-types-only, golden-pinned. Lives in src/core/present/ per orchestrator
+ *   override (supersedes design.md Decision 2 which placed it in src/cli/format/).
+ *   Reused by CLI (phase-4) AND Phase-5 MCP tool — "same source, same golden" (US-021).
+ *
+ * ADR-004: imports ONLY core model/port types — NO adapters, NO cli, NO mcp, NO drivers.
+ *   The existing test/core/boundaries.test.ts enforces this at CI.
+ * ADR-008: deterministic output — same (ExploreView, ExploreDetail) → byte-identical string.
+ *   No process.env / Date.now() / Math.random() / I/O anywhere in this file.
+ *
+ * --detail levels:
+ *   brief  — qname + kind + 1-line neighbor-kind counts
+ *   normal — brief + grouped neighbors (edge kind / direction / qname-sorted)
+ *   full   — normal + bodyHash + level + dynamic-SQL warning when payload.hasDynamicSql=true
+ */
+
+/** The detail level requested by the caller (--detail flag). */
+type ExploreDetail = 'brief' | 'normal' | 'full';
+/**
+ * Input bundle for formatExplore.
+ * Assembled by the caller from getNeighbors() + GraphNode (both core types).
+ * Design intentionally mirrors the future MCP ExploreToolInput.
+ */
+interface ExploreView {
+    readonly node: GraphNode;
+    readonly neighbors: NeighborGroups;
+}
+/**
+ * Formats an ExploreView into a human-readable string at the requested detail level.
+ *
+ * Output contract (ADR-008):
+ *   - Same (view, detail) → always the SAME bytes
+ *   - Trailing newline guaranteed
+ *   - No Date.now(), no process.env, no I/O
+ */
+declare function formatExplore(view: ExploreView, detail: ExploreDetail): string;
+
+/**
+ * formatSearch — task 1.2 (phase-5-mcp-server).
+ * Spec: dbgraph_search ranked paginated hits; Pagination.
+ * Design: PURE, core-types-only, golden-pinned. Lives in src/core/present/ per ADR-004.
+ *
+ * ADR-004: imports ONLY core model/port types — NO adapters, NO cli, NO mcp, NO drivers.
+ *   The existing test/core/boundaries.test.ts enforces this at CI.
+ * ADR-008: deterministic output — same (SearchView, SearchDetail) → byte-identical string.
+ *   No process.env / Date.now() / Math.random() / I/O anywhere in this file.
+ *
+ * --detail levels:
+ *   brief  — type + qname per hit, pagination footer
+ *   normal — brief + match column indicator
+ *   full   — normal + match column (body/comment/qname) explicitly labeled
+ */
+
+/** The detail level for search results. */
+type SearchDetail = 'brief' | 'normal' | 'full';
+/**
+ * Input bundle for formatSearch.
+ * Assembled by the caller from the search() result.
+ */
+interface SearchView {
+    readonly hits: readonly SearchHit[];
+    readonly total: number;
+    readonly offset: number;
+    readonly limit: number;
+}
+/**
+ * Formats a SearchView into a human-readable string at the requested detail level.
+ *
+ * Output contract (ADR-008):
+ *   - Same (view, detail) → always the SAME bytes
+ *   - Trailing newline guaranteed
+ *   - No Date.now(), no process.env, no I/O
+ */
+declare function formatSearch(view: SearchView, detail: SearchDetail): string;
+
+/**
+ * formatObject — task 1.3 (phase-5-mcp-server).
+ * Spec: dbgraph_object assembles full detail; Metadata-level states body omitted.
+ * Design: PURE, core-types-only, golden-pinned. Lives in src/core/present/ per ADR-004.
+ *
+ * ADR-004: imports ONLY core model/port types — NO adapters, NO cli, NO mcp, NO drivers.
+ * ADR-008: deterministic output — same (ObjectView, ObjectDetail) → byte-identical string.
+ *
+ * --detail levels:
+ *   brief  — header + annotation counts (idx/trg counts)
+ *   normal — brief + columns (type/null/default), PK/FK/check constraints
+ *   full   — normal + indexes (cols+kind), triggers (event), body for full-level modules
+ */
+
+/** The detail level for object output. */
+type ObjectDetail = 'brief' | 'normal' | 'full';
+/**
+ * Input bundle for formatObject.
+ * Assembled by the caller from getNodeByQName + getNeighbors.
+ */
+interface ObjectView {
+    readonly node: GraphNode;
+    readonly neighbors: NeighborGroups;
+}
+/**
+ * Formats an ObjectView into a human-readable string at the requested detail level.
+ *
+ * Output contract (ADR-008):
+ *   - Same (view, detail) → always the SAME bytes
+ *   - Trailing newline guaranteed
+ *   - No Date.now(), no process.env, no I/O
+ */
+declare function formatObject(view: ObjectView, detail: ObjectDetail): string;
+
+/**
+ * payload.ts — change explore-payloads (US-036).
+ * Spec: mcp-server "One shared payload-render helper backs explore and object";
+ *   cli-config "explore output comes from a pure formatter shared with the MCP tool".
+ *
+ * ONE pure module rendering the per-kind node payload as section-body lines. Both
+ * `formatObject` and `formatExplore` consume these renderers so the section bytes are
+ * byte-identical across surfaces (no per-surface branch, no drift — design D1/D2).
+ *
+ * Contract (design D1):
+ *   - Each renderer returns the section HEADER + one body row per entry, WITHOUT a
+ *     leading blank separator. Callers keep the inter-section `push('')` cadence, so
+ *     today's exact bytes are reproduced (refactor transparency).
+ *   - Each renderer returns [] when its group is empty.
+ *   - deriveColumnAnnotations computes the PK set + FK colname→target map ONCE. FK
+ *     target precedence (design D8): constraint payload `definition` when present,
+ *     else reconstructed from the `references` edges when unambiguous (Batch B),
+ *     else omitted — never guessed.
+ *
+ * ADR-004: imports ONLY core model types — NO adapters, NO cli, NO mcp, NO drivers.
+ * ADR-008: deterministic — same input → byte-identical string[]. No Date/env/random/I/O.
+ */
+
+/** A neighbor entry as returned by getNeighbors — the node plus its connecting edge. */
+interface NeighborEntry {
+    readonly node: GraphNode;
+    readonly edge?: GraphEdge;
+}
+/** Column-level annotations derived once from a node's constraint + references neighbors. */
+interface ColumnAnnotations {
+    /** Column names that participate in the primary key. */
+    readonly pk: ReadonlySet<string>;
+    /** FK column name → rendered target (payload definition, or reconstructed table-level qname). */
+    readonly fk: ReadonlyMap<string, string>;
+}
+/**
+ * Computes the PK column set and the FK colname→target map from a node's constraint
+ * neighbors. FK target precedence (design D8):
+ *   1. constraint payload `definition` present → rendered verbatim (column-level target).
+ *   2. (Batch B) payload target absent → reconstructed table-level target from the
+ *      `references` edges when unambiguous.
+ *   3. ambiguous / no resolvable target → omitted (honest degradation, never guessed).
+ */
+declare function deriveColumnAnnotations(constraints: readonly NeighborEntry[], references: readonly NeighborEntry[]): ColumnAnnotations;
+/** COLUMNS section: one row per column with type + PK/FK/NN markers and DEFAULT. */
+declare function renderColumns(columns: readonly NeighborEntry[], a: ColumnAnnotations): string[];
+/** CONSTRAINTS section: one row per constraint, FK column→target mapping via `a.fk`. */
+declare function renderConstraints(constraints: readonly NeighborEntry[], a: ColumnAnnotations): string[];
+/** INDEXES section: one row per index with UNIQUE + columns + optional [method]. */
+declare function renderIndexes(indexes: readonly NeighborEntry[]): string[];
+/** TRIGGERS section: one row per trigger with timing + events (from the fires_on.in group). */
+declare function renderTriggers(triggers: readonly NeighborEntry[]): string[];
+/**
+ * Renders a single non-container focus node's OWN per-kind payload line(s) using the
+ * SAME per-kind grammar as the section renderers (design D2). PK/FK markers appear on a
+ * column focus ONLY when parent-context annotations `a` are supplied; a bare column focus
+ * still shows type/nullable/default. Returns [] for a kind that has no focus payload line
+ * (e.g. a table/view — those render their full sections instead).
+ */
+declare function renderFocusPayload(node: GraphNode, a?: ColumnAnnotations): string[];
+
+/**
+ * formatRelated — task 1.4 (phase-5-mcp-server).
+ * Spec: dbgraph_related grouped by edge kind and direction; inferred edges separate group.
+ * Design: PURE, core-types-only, reuses ExploreView. Lives in src/core/present/ per ADR-004.
+ *
+ * ADR-004: imports ONLY core model/port types — NO adapters, NO cli, NO mcp, NO drivers.
+ * ADR-008: deterministic output — same (ExploreView, RelatedDetail) → byte-identical string.
+ *
+ * --detail levels:
+ *   brief  — grouped edge kinds with in+out counts
+ *   normal — brief + qnames per group (sorted)
+ *   full   — normal + inferred score for inferred edges
+ *
+ * Reuses ExploreView (node + neighbors map) — same shape as formatExplore input.
+ * Inferred edges (confidence='inferred') appear in a SEPARATE group with score.
+ */
+
+/** The detail level for related output. */
+type RelatedDetail = 'brief' | 'normal' | 'full';
+
+/**
+ * Formats an ExploreView into a related-neighbors string at the requested detail level.
+ *
+ * Output contract (ADR-008):
+ *   - Same (view, detail) → always the SAME bytes
+ *   - Trailing newline guaranteed
+ *   - No Date.now(), no process.env, no I/O
+ */
+declare function formatRelated(view: ExploreView, detail: RelatedDetail): string;
+
+/**
+ * formatImpact — task 1.5 (phase-5-mcp-server).
+ * Spec: dbgraph_impact read/write blast radius; Depth truncation and dynamic-SQL warn.
+ * Design: PURE; ImpactView { node; result: ImpactResult; resolve(id)→qname };
+ *   visible chain a→b→c, READ separated from WRITE, depth-truncation warning,
+ *   "impact possibly incomplete" when any node has_dynamic_sql.
+ *
+ * ADR-004: imports ONLY core model/port types — NO adapters, NO cli, NO mcp, NO drivers.
+ * ADR-008: deterministic output — same (ImpactView, ImpactDetail) → byte-identical string.
+ *
+ * --detail levels:
+ *   brief  — chain summary counts only
+ *   normal — full chain (a→b→c), read/write split
+ *   full   — normal + node kinds, dynamic-SQL / truncation warnings
+ */
+
+/** The detail level for impact output. */
+type ImpactDetail = 'brief' | 'normal' | 'full';
+/**
+ * Input bundle for formatImpact.
+ * Assembled by the caller from getImpact().
+ * resolve(id) maps node IDs in the chains to their qualified names.
+ */
+interface ImpactView {
+    readonly node: GraphNode;
+    readonly result: ImpactResult;
+    readonly resolve: (id: string) => string;
+}
+/**
+ * Formats an ImpactView into a human-readable string at the requested detail level.
+ *
+ * Output contract (ADR-008):
+ *   - Same (view, detail) → always the SAME bytes
+ *   - Trailing newline guaranteed
+ *   - No Date.now(), no process.env, no I/O
+ */
+declare function formatImpact(view: ImpactView, detail: ImpactDetail): string;
+
+/**
+ * formatPath — task 1.6 (phase-5-mcp-server).
+ * Spec: dbgraph_path shortest join path or suggests neighbors; No route reports neighbors.
+ * Design: PURE; PathView (PathResult + endpoint qnames); shortest route with exact join
+ *   columns per hop; inferred-only route marked inferred; no-route message + closest neighbors.
+ *
+ * ADR-004: imports ONLY core model/port types — NO adapters, NO cli, NO mcp, NO drivers.
+ * ADR-008: deterministic output — same (PathView) → byte-identical string.
+ *
+ * Note: formatPath has a single implicit detail level (path has no meaningful brief/full split).
+ */
+
+/**
+ * Input bundle for formatPath.
+ * Assembled by the caller from findJoinPath() + node qname resolution.
+ */
+interface PathView {
+    readonly from: string;
+    readonly to: string;
+    readonly result: PathResult;
+    readonly resolveTable: (id: string) => string;
+}
+/**
+ * Formats a PathView into a human-readable string.
+ *
+ * Output contract (ADR-008):
+ *   - Same (view) → always the SAME bytes
+ *   - Trailing newline guaranteed
+ *   - No Date.now(), no process.env, no I/O
+ */
+declare function formatPath(view: PathView): string;
+
+/**
+ * formatStatus — task 1.7 (phase-5-mcp-server).
+ * Spec: dbgraph_status index trust and live drift (connectionless half).
+ * Design: PURE; McpStatusView; engine/version, last sync, per-type counts, configured levels,
+ *   excluded objects, drift line ("could not be checked live" when no connection).
+ *
+ * ADR-004: imports ONLY core model/port types — NO adapters, NO cli, NO mcp, NO drivers.
+ * ADR-008: deterministic output — same (McpStatusView) → byte-identical string.
+ *
+ * This is the MCP variant of status, distinct from the CLI status formatter.
+ *
+ * --detail levels:
+ *   brief  — engine/version + last sync timestamp
+ *   normal — brief + per-type counts, configured levels
+ *   full   — normal + excluded objects, drift detail
+ */
+
+/** The detail level for status output. */
+type StatusDetail = 'brief' | 'normal' | 'full';
+/**
+ * Input bundle for formatStatus — MCP variant.
+ * Assembled by the caller from listSnapshots() + capabilitiesFor() + drift check.
+ */
+interface McpStatusView {
+    readonly engine: string;
+    readonly engineVersion: string | undefined;
+    readonly lastSync: string | null;
+    readonly counts: Readonly<Record<string, number>>;
+    readonly levels: Readonly<Partial<ObjectTypeLevels>>;
+    readonly excludedObjects: readonly string[];
+    readonly driftChecked: boolean;
+    readonly driftDetected: boolean | null;
+}
+/**
+ * Formats a McpStatusView into a human-readable string at the requested detail level.
+ *
+ * Output contract (ADR-008):
+ *   - Same (view) → always the SAME bytes
+ *   - Trailing newline guaranteed
+ *   - No Date.now(), no process.env, no I/O
+ */
+declare function formatStatus(view: McpStatusView, detail: StatusDetail): string;
+
+/**
+ * Typed error classes for dbgraph core.
+ * Design §7.1 — each error carries a stable code, extends DbgraphError,
+ * and has an actionable message. Never bare strings; nothing is swallowed.
+ */
+/**
+ * Base error class for all dbgraph errors.
+ * Carries a stable, machine-readable `code` for programmatic handling.
+ */
+declare class DbgraphError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Thrown when the normalizer encounters a structural violation in a RawCatalog.
+ * Message identifies which object and which field failed, e.g.:
+ *   "object dbo.orders: constraint FK_x has misaligned columns (2 src, 3 dst)"
+ */
+declare class NormalizationError extends DbgraphError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the SQLite adapter encounters a driver-level failure.
+ * Wraps the underlying error as `cause` so the driver's original stack is preserved.
+ */
+declare class StorageError extends DbgraphError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when the on-disk database was written by a newer version of dbgraph
+ * than the running binary supports (observed > supported).
+ * Message instructs the user to re-sync to rebuild the index.
+ */
+declare class SchemaVersionError extends DbgraphError {
+    readonly observed: number;
+    readonly supported: number;
+    constructor(observed: number, supported: number);
+}
+/**
+ * Thrown when a query is called with invalid parameters (e.g. depth < 1).
+ * Message describes the invalid parameter and its expected range.
+ */
+declare class QueryError extends DbgraphError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a requested node id or qname is not found in the graph store.
+ * Message identifies what was looked up and instructs the user to re-sync.
+ */
+declare class NotFoundError extends DbgraphError {
+    constructor(kind: string, identifier: string);
+}
+/**
+ * Thrown when configuration is invalid, malformed, or unsafe.
+ * Examples: missing required field, unknown dialect, inline plaintext credential,
+ * or an unset env variable referenced by ${env:VAR}.
+ * Message MUST be actionable — naming the offending field and corrective action.
+ */
+declare class ConfigError extends DbgraphError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a requested dialect has no registered adapter.
+ * Message names the bad dialect and lists the available dialects.
+ */
+declare class UnsupportedDialectError extends DbgraphError {
+    constructor(dialect: string);
+}
+
+/**
+ * A discriminated union of the actionable options presented to the user when no
+ * connectivity method can be established. Three variants MUST always be present.
+ *
+ * Design §"ConnectivityOutcome + options live in core" — these are pure data
+ * (engine-neutral, driver-free). Adapters BUILD the value; present/ RENDERS it.
+ */
+type ConnectivityOption = {
+    /** Emit the exact read-only catalog SELECT queries for the user to run themselves. */
+    readonly kind: 'run-it-yourself';
+    readonly description: string;
+    /** The EXACT read-only catalog SELECT statements, write-verb-free. */
+    readonly queries: readonly string[];
+} | {
+    /** Offer to install the missing driver/tool ONLY with explicit user consent. */
+    readonly kind: 'consented-install';
+    readonly description: string;
+    readonly tool: string;
+    readonly docUrl: string;
+} | {
+    /** Import a combined JSON dump the user produced externally. */
+    readonly kind: 'manual-dump';
+    readonly description: string;
+    readonly outputPath: string;
+};
+/**
+ * The structured, engine-neutral outcome yielded when no connectivity method
+ * can establish a connection. Carries at least three actionable options.
+ *
+ * Design §"typed throw, not return-type change" — thrown as ConnectivityUnavailableError.
+ * The summary field MUST be content-free (no schema names, object identifiers, or secrets).
+ */
+interface ConnectivityOutcome {
+    /** Stable engine identifier, e.g. 'mssql', 'pg', 'mysql', 'sqlite'. */
+    readonly engine: string;
+    /** Content-free human-readable summary. MUST NOT contain schema/identifier/secret. */
+    readonly summary: string;
+    /** Ordered list of strategies attempted and the reason each was skipped. */
+    readonly attempts: readonly StrategyAttempt[];
+    /** The at-least-three options offered to the user. Length MUST be >= 3. */
+    readonly options: readonly ConnectivityOption[];
+}
+/**
+ * Thrown when all connectivity strategies for an engine have been exhausted —
+ * none could both detect their prerequisite AND successfully probe a connection.
+ * Carries the ordered list of attempts and their individual reasons so callers
+ * and the CLI presenter can surface actionable guidance.
+ *
+ * Code: E_STRATEGY_EXHAUSTION.
+ * connectivity-strategies A1.3.
+ */
+declare class StrategyExhaustionError extends DbgraphError {
+    readonly attempts: readonly StrategyAttempt[];
+    constructor(attempts: readonly StrategyAttempt[]);
+}
+/**
+ * Thrown when a transport, format, or parse failure occurs during mssql catalog
+ * extraction via sqlcmd. The message is REDACTED — it never echoes raw stderr,
+ * host names, or connection-string identifiers. The raw cause (if any) is
+ * preserved as `error.cause` for debugging only and is never surfaced to the user.
+ *
+ * Code: E_TRANSPORT.
+ * connectivity MODIFIED requirement: "a transport/format/parse failure is
+ *   redacted into a typed error".
+ * resilient-connectivity R1 remediation (C2).
+ */
+declare class TransportError extends DbgraphError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when the engine adapter cannot connect to the source database.
+ * Covers: file not found, file not a valid database, database locked/busy,
+ * and required driver package not installed.
+ * Message MUST be actionable — naming the failing condition and the corrective action.
+ * Wraps the underlying driver error as `cause` so the original stack is preserved.
+ * US-026 / US-031.
+ */
+declare class ConnectionError extends DbgraphError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when a write or otherwise disallowed operation is attempted on a
+ * read-only source-database connection (US-031).
+ * Wraps the underlying driver error as `cause`.
+ */
+declare class PermissionError extends DbgraphError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when no connectivity method can be established for an engine.
+ * Carries a structured, engine-neutral `ConnectivityOutcome` with at least
+ * three actionable options (run-it-yourself, consented-install, manual-dump).
+ *
+ * Code: E_CONNECTIVITY_UNAVAILABLE.
+ * Design §"typed throw, not return-type change" — bubbles to cli.ts catch boundary.
+ * The message is content-free (carries outcome.summary only — no identifier/secret).
+ * resilient-connectivity Batch 1, task 1.2.
+ */
+declare class ConnectivityUnavailableError extends DbgraphError {
+    readonly outcome: ConnectivityOutcome;
+    constructor(outcome: ConnectivityOutcome);
+}
+
+/**
+ * formatOutcome — task 1.3 (resilient-connectivity Batch 1).
+ * Spec: connectivity-diagnostics "Connection failure yields a typed non-blocking outcome
+ *   presenting at least three options".
+ * Design: PURE; ConnectivityOutcome; engine + content-free summary, each attempt
+ *   (id — reason), ALL >= 3 options rendered deterministically.
+ *
+ * ADR-004: imports ONLY core types — NO adapters, NO cli, NO mcp, NO drivers.
+ * ADR-008: deterministic output — same (ConnectivityOutcome) → byte-identical string.
+ *
+ * Mirrors the SHAPE of present/status.ts: lines[], push, join('\n') + '\n'.
+ *
+ * Rendering contract per option kind:
+ *   run-it-yourself   — prints each query verbatim (paste-able, write-verb-free)
+ *   consented-install — prints tool + docUrl + explicit CONSENT notice (no auto-install)
+ *   manual-dump       — prints outputPath
+ */
+
+/**
+ * Formats a ConnectivityOutcome into a human-readable string.
+ *
+ * Output contract (ADR-008):
+ *   - Same (outcome) → always the SAME bytes
+ *   - Trailing newline guaranteed
+ *   - No Date.now(), no process.env, no I/O
+ */
+declare function formatOutcome(outcome: ConnectivityOutcome): string;
+
+/**
+ * formatDoctor — task 5.1 (resilient-connectivity Batch 5).
+ * Spec (US-043): connectivity-diagnostics "dbgraph doctor reports diagnostics content-free".
+ * Design: PURE; DoctorView; engine, native-driver bool, CLI tools + versions,
+ *   ODBC bool, resolved profile NAME, chosen-strategy id — SHAPE ONLY.
+ *   ZERO schema / identifier / secret.
+ *
+ * ADR-004: imports ONLY core types — NO adapters, NO cli, NO mcp, NO drivers.
+ * ADR-008: deterministic output — same (DoctorView) → byte-identical string.
+ *
+ * Mirrors the SHAPE of present/status.ts: lines[], push, join('\n') + '\n'.
+ *
+ * Content-free contract:
+ *   The renderer surfaces ONLY the capability-shape fields from DoctorView.
+ *   No schema names, object identifiers, connection-string values, or secrets
+ *   are ever surfaced — the output is safe to paste into a bug report.
+ */
+
+/**
+ * Input bundle for formatDoctor — a content-free capability snapshot.
+ *
+ * Fields contain SHAPE data only (booleans, version strings, profile names,
+ * strategy ids) — never schema names, object identifiers, or secrets.
+ */
+interface DoctorView {
+    /** Engine identifier (e.g. 'mssql', 'pg', 'mysql', 'sqlite'). */
+    readonly engine: string;
+    /**
+     * Whether the native driver package is importable in the current environment.
+     * True = driver present; false = absent.
+     */
+    readonly nativeDriver: boolean;
+    /**
+     * Detected CLI tools (e.g. sqlcmd, psql, mysql).
+     * Each entry carries the tool name, detected version (null if absent), and
+     * resolved PATH (null if absent).
+     */
+    readonly cliTools: readonly CliToolInfo[];
+    /**
+     * Whether an ODBC driver for this engine is registered in the OS.
+     * Always false for pg/mysql/sqlite (N/A).
+     */
+    readonly odbc: boolean;
+    /**
+     * The resolved profile name from the strategy registry.
+     * 'n/a' when no profile registry exists for this engine.
+     * 'unknown@any' when no matching profile was found (conservative default).
+     */
+    readonly resolvedProfile: string;
+    /**
+     * The chosen (or recommended) strategy id.
+     * 'unavailable' when no strategy can be selected.
+     */
+    readonly chosenStrategy: string;
+}
+/**
+ * Formats a DoctorView into a human-readable, content-free diagnostic string.
+ *
+ * Output contract (ADR-008):
+ *   - Same (view) → always the SAME bytes
+ *   - Trailing newline guaranteed
+ *   - No Date.now(), no process.env, no I/O
+ *   - CONTENT-FREE: only capability booleans, version strings, profile names,
+ *     and strategy ids are emitted — no schema/identifier/secret
+ */
+declare function formatDoctor(view: DoctorView): string;
+
+/**
+ * formatPrecheck — task 1.8 (phase-5-mcp-server).
+ * Spec: dbgraph_precheck aggregates DDL impact (format half).
+ * Design: PURE; PrecheckView; matched objects + aggregated impact sections
+ *   (triggers/writers/readers/constraints+indexes/what-to-test), confidence:'parsed' tags,
+ *   unmatched-identifier section.
+ *
+ * ADR-004: imports ONLY core model/port types — NO adapters, NO cli, NO mcp, NO drivers.
+ * ADR-008: deterministic output — same (PrecheckView, PrecheckDetail) → byte-identical string.
+ *
+ * --detail levels:
+ *   brief  — matched objects list only
+ *   normal — brief + aggregated impact sections
+ *   full   — normal + confidence tags, unmatched identifiers
+ */
+/** The detail level for precheck output. */
+type PrecheckDetail = 'brief' | 'normal' | 'full';
+/** An item in the precheck result — carries confidence and kind. */
+interface PrecheckItem {
+    readonly qname: string;
+    readonly kind: string;
+    readonly confidence: 'parsed';
+}
+/**
+ * Aggregated impact section for precheck output.
+ */
+interface PrecheckImpactSection {
+    readonly triggers: readonly PrecheckItem[];
+    readonly writers: readonly PrecheckItem[];
+    readonly readers: readonly PrecheckItem[];
+    readonly constraintsAndIndexes: readonly PrecheckItem[];
+    readonly whatToTest: readonly string[];
+}
+/**
+ * Input bundle for formatPrecheck.
+ * Assembled by the caller from DDL extraction + graph lookup + getImpact aggregation.
+ */
+interface PrecheckView {
+    readonly matchedObjects: readonly PrecheckItem[];
+    readonly impact: PrecheckImpactSection;
+    readonly unmatchedIdentifiers: readonly string[];
+}
+/**
+ * Formats a PrecheckView into a human-readable string at the requested detail level.
+ *
+ * Output contract (ADR-008):
+ *   - Same (view, detail) → always the SAME bytes
+ *   - Trailing newline guaranteed
+ *   - No Date.now(), no process.env, no I/O
+ */
+declare function formatPrecheck(view: PrecheckView, detail: PrecheckDetail): string;
+
+/**
+ * extractIdentifiers — task 4.3 / Batch D (phase-5-mcp-server).
+ * Spec: dbgraph_precheck extractor unit — conservative regex tokenizer.
+ * Design: PURE; reuses MSSQL tokenizer.ts [\w.]+ + bracket-strip patterns for
+ *   ALTER TABLE / CREATE|DROP INDEX / ADD|DROP COLUMN; case-insensitive, deduped.
+ *
+ * ADR-004: imports NOTHING from adapters, cli, mcp, or drivers. PURE function.
+ * ADR-007: no node-sql-parser — conservative regex only.
+ * ADR-008: deterministic — same ddl → same readonly string[].
+ *
+ * Placement: src/core/precheck/ — neutral module shared by BOTH MCP tool
+ * (src/mcp/tools/precheck.ts) and CLI command (src/cli/commands/affected.ts)
+ * via the barrel. Neither cli nor mcp imports the other (ADR-004 boundary).
+ */
+/**
+ * Extracts qualified identifiers from DDL statements using conservative
+ * regex patterns (ALTER TABLE, CREATE|DROP INDEX, ADD|DROP COLUMN).
+ *
+ * Returns a deduped, stable sorted readonly array of lowercased identifiers.
+ * Bracket delimiters are stripped. Case is normalized to lowercase.
+ *
+ * Only recognized statement patterns yield identifiers — unrecognized DDL
+ * produces no identifiers (SELECT, INSERT, etc. are silently ignored).
+ *
+ * @param ddl  Raw DDL string (one or more statements, separated by semicolons).
+ * @returns    Readonly, deduped, sorted array of extracted identifiers.
+ */
+declare function extractIdentifiers(ddl: string): readonly string[];
+
+/**
+ * runPrecheck — precheck engine, task 4.3 / Batch D (phase-5-mcp-server).
+ * Spec: match extracted identifiers to graph → aggregate getImpact → PrecheckView.
+ * Design: PURE core (store, ddl) → PrecheckView; tags confidence:'parsed';
+ *   reports unmatched identifiers; deduplicates impact across multiple statements.
+ *
+ * ADR-004: imports ONLY core query fns + core ports. NO adapters, NO cli, NO mcp.
+ * ADR-007: no node-sql-parser. ADR-008: deterministic output.
+ *
+ * Placement: src/core/precheck/ — neutral module consumed by BOTH
+ *   src/mcp/tools/precheck.ts AND src/cli/commands/affected.ts via the barrel.
+ *   Neither cli nor mcp imports the other (ADR-004 boundary preserved).
+ */
+
+/**
+ * Extracts identifiers from `ddl`, matches them against the graph,
+ * aggregates `getImpact` across all matched objects, and returns a
+ * `PrecheckView` ready for `formatPrecheck`.
+ *
+ * Every matched item and impact item carries `confidence: 'parsed'`.
+ * Identifiers that match no graph node appear in `unmatchedIdentifiers`.
+ * Impact sections are deduplicated across all statements.
+ *
+ * @param store  The open GraphStore (read-only; no writes issued).
+ * @param ddl    Raw DDL string (one or more statements).
+ * @returns      PrecheckView with matchedObjects, impact, unmatchedIdentifiers.
+ */
+declare function runPrecheck(store: GraphStore, ddl: string): Promise<PrecheckView>;
+
+/**
+ * Factory for the SQLite GraphStore adapter.
+ * Design §2 (factory join point) + §10 (sequence diagram).
+ *
+ * createSqliteGraphStore(opts) is the ONLY place where:
+ *  1. The driver is selected and opened (ADR-004: driver never pulled into core).
+ *  2. The raw DB is opened + migrations are run.
+ *  3. A GraphStore-conforming adapter is returned.
+ *
+ * Phase 9.5b: the standalone `await import('better-sqlite3')` is REMOVED — the
+ * dynamic import now lives inside `openRawDb`'s better-sqlite3 path in schema.ts.
+ * factory.ts calls `openRawDb(path)` (now async, returns `WritableSqliteHandle`),
+ * passes the handle to `runMigrations` and `new SqliteGraphStore`. Default driver
+ * stays better-sqlite3; no `driver` option yet (added in Batch 2).
+ *
+ * Note: this adapter is under src/adapters/storage/sqlite/ — it is EXEMPT from
+ * the write-verb security scan that targets src/adapters/engines/* (source-extraction
+ * paths). The local index MUST write (CREATE TABLE, INSERT/UPSERT, DELETE) to its
+ * own .dbgraph database file by design (ADR-005). This exemption is documented here
+ * so Batch D boundary/security tests can scope correctly.
+ *
+ * Imports allowed: core types/ports only + storage-layer modules.
+ */
+
+interface SqliteGraphStoreOptions {
+    /** Filesystem path to the SQLite database file, or ':memory:' for in-memory. */
+    readonly path: string;
+    /**
+     * SQLite driver to use. Default: `'better-sqlite3'` (byte-identical default path).
+     * Use `'node:sqlite'` to opt-in to the built-in Node.js SQLite driver (Node >= 22.5).
+     *
+     * Explicit selection only — NO silent fallback. Requesting `'node:sqlite'` on
+     * Node < 22.5 throws an explicit error. Existing callers that pass no `driver`
+     * continue using `'better-sqlite3'` unchanged (ADR-008, byte-identical guarantee).
+     */
+    readonly driver?: 'better-sqlite3' | 'node:sqlite';
+}
+/**
+ * Opens the SQLite graph store at `opts.path`, runs forward migrations if needed,
+ * and returns a GraphStore-conforming adapter.
+ *
+ * @param opts.path - ':memory:' or an absolute path to the .dbgraph/dbgraph.db file.
+ * @throws SchemaVersionError if the on-disk schema is newer than supported.
+ * @throws StorageError if the database cannot be opened.
+ */
+declare function createSqliteGraphStore(opts: SqliteGraphStoreOptions): Promise<GraphStore>;
+
+/**
+ * createSqliteSchemaAdapter — factory for the SQLite schema extraction adapter.
+ * Design §5.1 — the ONLY join point between core and the SQLite driver.
+ *
+ * Responsibilities:
+ *   1. Explicit driver selection (default: better-sqlite3; NO silent auto-fallback).
+ *   2. Dynamic import of the chosen driver (ADR-004: driver never pulled into core).
+ *   3. Open read-only with fileMustExist flags.
+ *   4. Map driver-level open errors to typed ConnectionError / PermissionError.
+ *   5. Wrap the raw handle in ReadonlyDriver and return a SqliteSchemaAdapter.
+ *
+ * node:sqlite requires Node >= 22.5; requesting it on an older runtime throws
+ * ConnectionError with an actionable message (design §2 — no silent downgrade).
+ *
+ * US-026 (first concrete adapter), US-031 (read-only by construction).
+ */
+
+/**
+ * Opens a SQLite source database in read-only mode and returns a SchemaAdapter.
+ * The adapter is already-open — no `open()` call is needed (mirrors createSqliteGraphStore).
+ *
+ * @param config.file    - Absolute path to the source .db file.
+ * @param config.driver  - 'better-sqlite3' (default) | 'node:sqlite'. Explicit selection,
+ *                         no silent fallback.
+ * @throws ConnectionError  if the file is missing, not a valid SQLite db, db is locked,
+ *                          or the required driver package is not installed.
+ * @throws ConnectionError  if node:sqlite is requested on Node < 22.5.
+ */
+declare function createSqliteSchemaAdapter(config: SqliteAdapterConfig): Promise<SchemaAdapter>;
+
+/**
+ * createMssqlSchemaAdapter — strategy-backed factory for the SQL Server schema adapter.
+ * Design §"Registry lives in the factory; selection iterates in priority order".
+ *
+ * Responsibilities:
+ *   1. Build ordered strategy list from config via buildMssqlStrategies.
+ *   2. Probe strategies in order via selectStrategy (detect + canConnect).
+ *   3. Wrap the winning strategy in StrategyBackedSchemaAdapter.
+ *   4. Return the adapter — already-connected, no open() call needed.
+ *
+ * Back-compat:
+ *   - sql/ntlm configs → NativeTediousStrategy wins (same behavior as before).
+ *   - integrated config → NativeTediousStrategy is omitted; SqlcmdStrategy is tried.
+ *   - Missing 'mssql' driver for explicit-cred configs → ConnectionError('npm i mssql').
+ *
+ * US-027 (SQL Server adapter), ADR-004 (seam), ADR-006 (lazy optional import).
+ * connectivity-strategies Batch C, task C3.3.
+ */
+
+/**
+ * Optional dependencies for createMssqlSchemaAdapter.
+ * All fields are optional — omit entirely for production use.
+ */
+interface MssqlSchemaAdapterDeps {
+    /** Logger port instance for strategy-selection transparency. Defaults to noopLogger. */
+    readonly logger?: Logger;
+    /** Override NativeTediousStrategy constructor — for testing only. */
+    readonly NativeTedious?: new (config: MssqlAdapterConfig) => ConnectivityStrategy;
+    /** Override SqlcmdStrategy constructor — for testing only. */
+    readonly Sqlcmd?: new (config: MssqlAdapterConfig) => ConnectivityStrategy;
+    /** Override ManualDumpStrategy constructor — for testing only. */
+    readonly ManualDump?: new (config: MssqlAdapterConfig) => ConnectivityStrategy;
+    /** Override ConsentedInstallStrategy constructor — for testing only. */
+    readonly ConsentedInstall?: new (config: MssqlAdapterConfig, logger: Logger, os?: string) => ConnectivityStrategy;
+}
+/**
+ * Opens a SQL Server connection (or prepares an external-tool strategy) and
+ * returns a SchemaAdapter. The adapter is already-connected — no open() call needed.
+ *
+ * Strategy selection order (see registry.ts):
+ *   1. NativeTediousStrategy — explicit-credential (sql/ntlm) configs only
+ *   2. SqlcmdStrategy        — integrated auth or fallback if native fails
+ *
+ * @param config - MssqlAdapterConfig: server/database/authentication/TLS options.
+ * @param deps   - Optional deps for selection transparency and testability.
+ *
+ * @throws ConnectionError if mssql is not installed for an explicit-cred config
+ *         (native strategy propagates the 'npm i mssql' message — back-compat).
+ * @throws ConnectionError if native pool cannot connect (credentials, network, TLS).
+ * @throws StrategyExhaustionError if all strategies fail to detect + connect.
+ */
+declare function createMssqlSchemaAdapter(config: MssqlAdapterConfig, deps?: MssqlSchemaAdapterDeps): Promise<SchemaAdapter>;
+
+/**
+ * Minimal duck-typed interface for a pg.Client.
+ * Typed locally so we do not need to import pg here — the client instance
+ * is created and connected by the factory and passed in.
+ *
+ * pg.Client.query(sql, params?) returns { rows: Record<string, unknown>[] }
+ * pg.Client.end   releases the connection socket.
+ */
+interface ClientLike {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+    end(): Promise<void>;
+}
+
+/**
+ * createPgSchemaAdapter — factory for the PostgreSQL schema extraction adapter.
+ * Design §"PG mirrors the SQLite adapter SHAPE — collapse lazy-import + connect
+ *   + fingerprint logic directly into factory.ts".
+ *
+ * Responsibilities:
+ *   1. Lazy dynamic import('pg' as string) — ADR-006: NO top-level pg import.
+ *   2. Build the pg connection config (host, port default 5432, database, user,
+ *      password already resolved from ${env:VAR} by the caller, optional ssl).
+ *   3. new Client(connConfig) + client.connect() — one short-lived Client per run.
+ *   4. Map connect failures via mapPgError to typed errors (ConnectionError /
+ *      PermissionError).
+ *   5. Wrap the connected client in createPgReadonlyDriver → PgSchemaAdapter.
+ *   6. Missing 'pg' package → ConnectionError('... npm i pg').
+ *
+ * NO strategy registry (that is SQL-Server-only machinery).
+ * createPgSchemaAdapter is the ONLY join point (ADR-004).
+ *
+ * US-028 (PostgreSQL adapter), ADR-004 (seam), ADR-006 (lazy optional import),
+ * pg-extraction spec "Absent pg driver names npm i pg".
+ */
+
+/**
+ * Optional dependencies for createPgSchemaAdapter.
+ * All fields are optional — omit entirely for production use.
+ *
+ * - `Client`   — inject a fake pg.Client constructor in unit tests so no real
+ *                pg install is required. Production code uses the lazily-imported
+ *                pg.Client.
+ * - `importPg` — inject a fake dynamic import function to test the missing-driver
+ *                error path without actually uninstalling pg.
+ */
+interface PgSchemaAdapterDeps {
+    /**
+     * pg.Client constructor override — for unit testing only.
+     * When provided, the factory skips the lazy import and uses this constructor.
+     */
+    readonly Client?: new (config: Record<string, unknown>) => ClientLike & {
+        connect(): Promise<void>;
+    };
+    /**
+     * Dynamic import override — for testing the MODULE_NOT_FOUND path only.
+     * When provided, the factory calls this instead of `import('pg' as string)`.
+     */
+    readonly importPg?: () => unknown;
+}
+/**
+ * Opens a PostgreSQL connection and returns a SchemaAdapter.
+ * The adapter is already-connected — no open() call needed.
+ *
+ * @param config - PgAdapterConfig: host/port/database/user/password (resolved) + optional ssl/schema.
+ * @param deps   - Optional deps for testing (Client constructor / importPg override).
+ *
+ * @throws ConnectionError if pg is not installed (`npm i pg` in message — ADR-006).
+ * @throws ConnectionError if client.connect() fails (network / db missing / auth).
+ * @throws PermissionError if client.connect() fails with insufficient privilege.
+ */
+declare function createPgSchemaAdapter(config: PgAdapterConfig, deps?: PgSchemaAdapterDeps): Promise<SchemaAdapter>;
+
+/**
+ * MysqlReadonlyDriver — async engine-local seam over mysql2/promise connection.
+ * Design §driver.ts — "single duck-typed MysqlReadonlyDriver seam".
+ *
+ * The adapter and map.ts talk ONLY to this interface — never to mysql2 directly.
+ * Mirrors pg/driver.ts but adapts to mysql2/promise createConnection (NOT a pool):
+ * one short-lived connection per extraction run, then conn.end().
+ *
+ * mysql2/promise result shape: [rows, fields] (tuple)
+ * vs PG shape:                 { rows: Record<string, unknown>[] }
+ *
+ * The seam normalizes [rows, fields] → rows so the adapter and map.ts consume
+ * a uniform Record<string, unknown>[] shape — identical to the PG driver surface.
+ * (Decision D2: the seam absorbs the dialect shape difference.)
+ *
+ * query() accepts an optional params array for parameterized queries (? params).
+ * All catalog queries in mysql use DATABASE() (a function, not a bind param), so
+ * params will generally be undefined — but the signature matches the pg seam.
+ *
+ * NO top-level mysql2 import anywhere (ADR-006). The lazy import lives in factory.ts.
+ * The adapter talks ONLY to MysqlReadonlyDriver (ADR-004).
+ *
+ * US-029 (MySQL adapter, Phase 8b), ADR-004 (seam keeps mysql2 out of core),
+ * ADR-006 (lazy optional import).
+ */
+/**
+ * Minimal duck-typed interface for a mysql2/promise connection.
+ * Typed locally so we do NOT import mysql2 in this file at module level.
+ * The connection instance is created and connected by the factory and passed in.
+ *
+ * mysql2/promise connection.query(sql, params?) returns [rows, fields].
+ * connection.end() releases the connection socket.
+ *
+ * Decision D3: we use query() (text protocol, zero params for DATABASE() scoped
+ * queries) rather than execute() (prepared/binary), matching the conservative
+ * read-only posture and avoiding prepared-statement protocol restrictions.
+ */
+interface ConnectionLike {
+    query(sql: string, params?: unknown[]): Promise<[Record<string, unknown>[], unknown]>;
+    end(): Promise<void>;
+}
+
+/**
+ * createMysqlSchemaAdapter — factory for the MySQL schema extraction adapter.
+ * Design §"collapse lazy-import + connect + error mapping directly into factory.ts"
+ *   (pg/SQLite shape — no strategy registry; MySQL has flat host/port/user/password + ssl).
+ *
+ * Responsibilities:
+ *   1. Lazy dynamic import('mysql2/promise' as string) — ADR-006: NO top-level mysql2 import.
+ *   2. Build the mysql2 connection config (host, port default 3306, database, user,
+ *      password already resolved from ${env:VAR} by the caller, optional ssl).
+ *   3. createConnection(connConfig) + connection.connect() — one short-lived connection per run.
+ *   4. Map connect failures via mapMysqlError to typed errors (ConnectionError / PermissionError).
+ *   5. Wrap the connected connection in createMysqlReadonlyDriver → MysqlSchemaAdapter.
+ *   6. Missing 'mysql2' package → ConnectionError('... npm i mysql2').
+ *
+ * NO strategy registry (that is SQL-Server-only machinery).
+ * createMysqlSchemaAdapter is the ONLY join point (ADR-004, ADR-006).
+ *
+ * US-029 (MySQL adapter, Phase 8b), ADR-004 (seam), ADR-006 (lazy optional import),
+ * mysql-extraction spec "Absent mysql2 driver names npm i mysql2".
+ */
+
+/**
+ * Optional dependencies for createMysqlSchemaAdapter.
+ * All fields are optional — omit entirely for production use.
+ *
+ * - `createConnection` — inject a fake mysql2 createConnection function in unit
+ *                        tests so no real mysql2 install is required. Production code
+ *                        uses the lazily-imported mysql2/promise.createConnection.
+ * - `importMysql`      — inject a fake dynamic import function to test the missing-driver
+ *                        error path without actually uninstalling mysql2.
+ */
+interface MysqlSchemaAdapterDeps {
+    /**
+     * mysql2/promise createConnection override — for unit testing only.
+     * When provided, the factory skips the lazy import and uses this function.
+     *
+     * Matches the real mysql2/promise.createConnection() signature:
+     *   createConnection(config) => Promise<Connection>
+     * The Promise resolves with an already-connected ConnectionLike (no .connect() call needed).
+     */
+    readonly createConnection?: (config: Record<string, unknown>) => Promise<ConnectionLike>;
+    /**
+     * Dynamic import override — for testing the MODULE_NOT_FOUND path only.
+     * When provided, the factory calls this instead of import('mysql2/promise' as string).
+     */
+    readonly importMysql?: () => Promise<unknown>;
+}
+/**
+ * Opens a MySQL connection and returns a SchemaAdapter.
+ * The adapter is already-connected — no open() call needed.
+ *
+ * @param config - MysqlAdapterConfig: host/port/database/user/password (resolved) + optional ssl.
+ * @param deps   - Optional deps for testing (createConnection override / importMysql override).
+ *
+ * @throws ConnectionError if mysql2 is not installed (`npm i mysql2` in message — ADR-006).
+ * @throws ConnectionError if connection.connect() fails (network / db missing / auth).
+ * @throws PermissionError if connection.connect() fails with insufficient privilege.
+ */
+declare function createMysqlSchemaAdapter(config: MysqlAdapterConfig, deps?: MysqlSchemaAdapterDeps): Promise<SchemaAdapter>;
+
+/**
+ * Minimal cursor-like shape returned by mongodb collection operations.
+ * Typed locally so we do NOT need to import mongodb in this file.
+ */
+interface CursorLike<T = Record<string, unknown>> {
+    toArray(): Promise<T[]>;
+}
+/**
+ * Minimal duck-typed interface for a mongodb collection.
+ * Typed locally — no top-level mongodb import.
+ */
+interface CollectionLike {
+    aggregate(pipeline: Record<string, unknown>[]): CursorLike;
+    listIndexes(): CursorLike;
+}
+/**
+ * Minimal duck-typed interface for a mongodb Db instance.
+ * Typed locally — no top-level mongodb import.
+ *
+ * listCollections().toArray() returns collection info objects.
+ * command(cmd) runs an administrative command (dbStats, etc.).
+ * collection(name) accesses a named collection.
+ */
+interface DbLike {
+    listCollections(filter?: Record<string, unknown>, options?: Record<string, unknown>): CursorLike<{
+        name: string;
+        options?: Record<string, unknown>;
+    }>;
+    command(cmd: Record<string, unknown>): Promise<Record<string, unknown>>;
+    collection(name: string): CollectionLike;
+}
+/**
+ * Minimal duck-typed interface for a mongodb MongoClient.
+ * Typed locally — no top-level mongodb import (ADR-006).
+ *
+ * connect() must be called before using the client.
+ * db(name)  returns a Db instance for the named database.
+ * close()   releases the connection.
+ */
+interface MongoClientLike {
+    connect(): Promise<void>;
+    db(name: string): DbLike;
+    close(): Promise<void>;
+}
+
+/**
+ * createMongodbSchemaAdapter — factory for the MongoDB schema extraction adapter.
+ * Design §"collapse lazy-import + connect + error mapping directly into factory.ts"
+ *   (pg/mysql shape — no strategy registry; MongoDB uses URI-based config).
+ *
+ * Responsibilities:
+ *   1. Lazy dynamic import('mongodb' as string) — ADR-006: NO top-level mongodb import.
+ *   2. Instantiate MongoClient with the resolved URI + optional tls flag.
+ *   3. client.connect() — one short-lived MongoClient per extraction run.
+ *   4. Map connect failures via mapMongoError to typed errors
+ *      (ConnectionError / PermissionError / ConnectivityUnavailableError).
+ *   5. Wrap the connected client in createMongodbReadonlyDriver → MongodbSchemaAdapter.
+ *   6. Missing 'mongodb' package → ConnectivityUnavailableError with "npm i mongodb" in summary.
+ *
+ * NO strategy registry (that is SQL-Server-only machinery).
+ * createMongodbSchemaAdapter is the ONLY join point (ADR-004, ADR-006).
+ *
+ * US-030 (MongoDB adapter), ADR-004 (seam), ADR-006 (lazy optional import),
+ * mongodb-extraction spec "Absent mongodb driver names npm i mongodb".
+ */
+
+/**
+ * Optional dependencies for createMongodbSchemaAdapter.
+ * All fields are optional — omit entirely for production use.
+ *
+ * - `MongoClient`   — inject a fake MongoClient constructor in unit tests so no real
+ *                     mongodb install is required. Production code uses the lazily-imported
+ *                     mongodb MongoClient.
+ * - `importMongodb` — inject a fake dynamic import function to test the missing-driver
+ *                     error path without actually uninstalling mongodb.
+ */
+interface MongodbSchemaAdapterDeps {
+    /**
+     * MongoClient constructor override — for unit testing only.
+     * When provided, the factory skips the lazy import and uses this constructor.
+     */
+    readonly MongoClient?: new (uri: string, options?: Record<string, unknown>) => MongoClientLike;
+    /**
+     * Dynamic import override — for testing the MODULE_NOT_FOUND path only.
+     * When provided, the factory calls this instead of import('mongodb' as string).
+     */
+    readonly importMongodb?: () => Promise<unknown>;
+}
+/**
+ * Opens a MongoDB connection and returns a SchemaAdapter.
+ * The adapter is already-connected — no open() call needed.
+ *
+ * @param config - MongodbAdapterConfig: uri/database (resolved) + optional sampleSize/tls.
+ * @param deps   - Optional deps for testing (MongoClient constructor / importMongodb override).
+ *
+ * @throws ConnectivityUnavailableError if mongodb is not installed (summary has "npm i mongodb").
+ * @throws ConnectivityUnavailableError if client.connect() fails (network / auth / role).
+ */
+declare function createMongodbSchemaAdapter(config: MongodbAdapterConfig, deps?: MongodbSchemaAdapterDeps): Promise<SchemaAdapter>;
+
+/**
+ * MssqlCapabilityProbe — CapabilityProbe implementation for SQL Server.
+ * Design §"probe() is OPTIONAL on the strategy port; per-engine probe in adapters".
+ * Resilient-connectivity Batch 2, task 2.1.
+ *
+ * Detection strategy:
+ *   - nativeDriver: dynamic import('tedious') resolves → present (NO .connect())
+ *   - cliTools:     where/which sqlcmd on PATH (cross-platform); version via sqlcmd -?
+ *   - odbc:         Windows registry probe (mirrors OdbcDriverStrategy.detect())
+ *
+ * All detection failures, timeouts, and absent prerequisites yield a NEGATIVE
+ * result — probe() MUST NEVER reject.
+ *
+ * Seams (all optional — omit for production use):
+ *   - spawnSync:      injectable child_process.spawnSync (default: real spawnSync)
+ *   - importTedious:  injectable import() for 'tedious' (default: real dynamic import)
+ *   - platform:       injectable process.platform override (for cross-platform testing)
+ *
+ * ADR-004: this file MAY import node:child_process (adapter territory).
+ * The core port (capability-probe.ts) imports nothing from adapters.
+ */
+
+/**
+ * Injectable seam for node:child_process.spawnSync (Buffer overload).
+ * Mirrors the existing SqlcmdStrategy / OdbcDriverStrategy seam pattern.
+ */
+type SpawnSyncFn$3 = (command: string, args: readonly string[], options: SpawnSyncOptions) => SpawnSyncReturns<Buffer>;
+/**
+ * Injectable seam for dynamic import('tedious').
+ * Resolves with the module (any shape) when present; rejects on MODULE_NOT_FOUND.
+ * MUST NOT call .connect() or instantiate any class.
+ */
+type ImportTediousFn = () => Promise<unknown>;
+/**
+ * Constructor options for MssqlCapabilityProbe.
+ * All fields are optional — omit entirely for production use.
+ */
+interface MssqlCapabilityProbeOptions {
+    /** Injectable spawnSync seam. Defaults to node:child_process.spawnSync. */
+    readonly spawnSync?: SpawnSyncFn$3;
+    /** Injectable tedious import seam. Defaults to dynamic import('tedious'). */
+    readonly importTedious?: ImportTediousFn;
+    /** Injectable platform override for cross-platform PATH detection testing. */
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * Capability probe for SQL Server.
+ * Implements CapabilityProbe — engine = 'mssql'.
+ *
+ * probe() MUST resolve, never reject.
+ * probe() MUST NOT open a DB connection.
+ * probe() MUST NOT issue any write.
+ */
+declare class MssqlCapabilityProbe implements CapabilityProbe {
+    readonly engine = "mssql";
+    private readonly _spawnSync;
+    private readonly _importTedious;
+    private readonly _platform;
+    constructor(opts?: MssqlCapabilityProbeOptions);
+    /**
+     * Run all three detections (driver, CLI, ODBC) and return the composite result.
+     * Any detection failure is reported as unavailable — never throws.
+     */
+    probe(): Promise<ProbeResult>;
+    /**
+     * Checks whether the 'tedious' npm package is importable WITHOUT connecting.
+     * Resolves true on success, false on any error (MODULE_NOT_FOUND, throws, etc.).
+     */
+    private _detectNativeDriver;
+    /**
+     * Scans for sqlcmd on PATH using where (Windows) / which (POSIX).
+     * If found, parses the version from sqlcmd -?.
+     * Always resolves with one CliToolInfo entry for 'sqlcmd'.
+     */
+    private _detectCliTools;
+    private _detectSqlcmd;
+    /**
+     * Runs sqlcmd -? to extract the version string.
+     * Returns null on any failure (timeout, non-zero exit, parse failure).
+     */
+    private _parseSqlcmdVersion;
+    /**
+     * Probes the Windows registry for an ODBC Driver for SQL Server installation.
+     * Mirrors OdbcDriverStrategy.detect() — returns true/false, never throws.
+     */
+    private _detectOdbc;
+}
+
+/**
+ * PgCapabilityProbe — CapabilityProbe implementation for PostgreSQL.
+ * Design §"probe() is OPTIONAL on the strategy port; per-engine probe in adapters".
+ * Resilient-connectivity Batch 2, task 2.2.
+ *
+ * Detection strategy:
+ *   - nativeDriver: dynamic import('pg') resolves → present (NO Client.connect())
+ *   - cliTools:     where/which psql on PATH (cross-platform); version via psql --version
+ *   - odbc:         always false (N/A for PostgreSQL)
+ *
+ * All detection failures, timeouts, and absent prerequisites yield a NEGATIVE
+ * result — probe() MUST NEVER reject.
+ *
+ * Seams (all optional — omit for production use):
+ *   - spawnSync:  injectable child_process.spawnSync
+ *   - importPg:   injectable import() for 'pg' (mirrors factory.ts PgSchemaAdapterDeps.importPg)
+ *   - platform:   injectable process.platform override (for cross-platform testing)
+ *
+ * ADR-004: this file MAY import node:child_process (adapter territory).
+ */
+
+/**
+ * Injectable seam for node:child_process.spawnSync (Buffer overload).
+ * Mirrors the SqlcmdStrategy / OdbcDriverStrategy seam pattern.
+ */
+type SpawnSyncFn$2 = (command: string, args: readonly string[], options: SpawnSyncOptions) => SpawnSyncReturns<Buffer>;
+/**
+ * Injectable seam for dynamic import('pg').
+ * Resolves with the module when present; rejects on MODULE_NOT_FOUND.
+ * MUST NOT call Client.connect() or instantiate any class.
+ */
+type ImportPgFn = () => Promise<unknown>;
+/**
+ * Constructor options for PgCapabilityProbe.
+ * All fields are optional — omit entirely for production use.
+ */
+interface PgCapabilityProbeOptions {
+    /** Injectable spawnSync seam. Defaults to node:child_process.spawnSync. */
+    readonly spawnSync?: SpawnSyncFn$2;
+    /** Injectable pg import seam. Defaults to dynamic import('pg'). */
+    readonly importPg?: ImportPgFn;
+    /** Injectable platform override for cross-platform PATH detection testing. */
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * Capability probe for PostgreSQL.
+ * Implements CapabilityProbe — engine = 'pg'.
+ *
+ * probe() MUST resolve, never reject.
+ * probe() MUST NOT open a DB connection.
+ * probe() MUST NOT issue any write.
+ */
+declare class PgCapabilityProbe implements CapabilityProbe {
+    readonly engine = "pg";
+    private readonly _spawnSync;
+    private readonly _importPg;
+    private readonly _platform;
+    constructor(opts?: PgCapabilityProbeOptions);
+    /**
+     * Run all detections (driver, CLI) and return the composite result.
+     * Any detection failure is reported as unavailable — never throws.
+     * odbc is always false for PostgreSQL.
+     */
+    probe(): Promise<ProbeResult>;
+    /**
+     * Checks whether the 'pg' npm package is importable WITHOUT connecting.
+     * Resolves true on success, false on any error.
+     */
+    private _detectNativeDriver;
+    /**
+     * Scans for psql on PATH using where (Windows) / which (POSIX).
+     * If found, parses the version from psql --version.
+     * Always resolves with one CliToolInfo entry for 'psql'.
+     */
+    private _detectCliTools;
+    private _detectPsql;
+    /**
+     * Runs psql --version to extract the version string.
+     * Returns null on any failure.
+     */
+    private _parsePsqlVersion;
+}
+
+/**
+ * MysqlCapabilityProbe — CapabilityProbe implementation for MySQL.
+ * Design §"probe() is OPTIONAL on the strategy port; per-engine probe in adapters".
+ * Resilient-connectivity Batch 2, task 2.3.
+ *
+ * Detection strategy:
+ *   - nativeDriver: dynamic import('mysql2') resolves → present (NO createConnection())
+ *   - cliTools:     where/which mysql on PATH (cross-platform); version via mysql --version
+ *   - odbc:         always false (N/A for MySQL)
+ *
+ * All detection failures, timeouts, and absent prerequisites yield a NEGATIVE
+ * result — probe() MUST NEVER reject.
+ *
+ * Seams (all optional — omit for production use):
+ *   - spawnSync:    injectable child_process.spawnSync
+ *   - importMysql:  injectable import() for 'mysql2' (mirrors factory.ts MysqlSchemaAdapterDeps.importMysql)
+ *   - platform:     injectable process.platform override (for cross-platform testing)
+ *
+ * ADR-004: this file MAY import node:child_process (adapter territory).
+ */
+
+/**
+ * Injectable seam for node:child_process.spawnSync (Buffer overload).
+ * Mirrors the SqlcmdStrategy / OdbcDriverStrategy seam pattern.
+ */
+type SpawnSyncFn$1 = (command: string, args: readonly string[], options: SpawnSyncOptions) => SpawnSyncReturns<Buffer>;
+/**
+ * Injectable seam for dynamic import('mysql2').
+ * Resolves with the module when present; rejects on MODULE_NOT_FOUND.
+ * MUST NOT call createConnection() or establish any connection.
+ */
+type ImportMysqlFn = () => Promise<unknown>;
+/**
+ * Constructor options for MysqlCapabilityProbe.
+ * All fields are optional — omit entirely for production use.
+ */
+interface MysqlCapabilityProbeOptions {
+    /** Injectable spawnSync seam. Defaults to node:child_process.spawnSync. */
+    readonly spawnSync?: SpawnSyncFn$1;
+    /** Injectable mysql2 import seam. Defaults to dynamic import('mysql2'). */
+    readonly importMysql?: ImportMysqlFn;
+    /** Injectable platform override for cross-platform PATH detection testing. */
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * Capability probe for MySQL.
+ * Implements CapabilityProbe — engine = 'mysql'.
+ *
+ * probe() MUST resolve, never reject.
+ * probe() MUST NOT open a DB connection.
+ * probe() MUST NOT issue any write.
+ */
+declare class MysqlCapabilityProbe implements CapabilityProbe {
+    readonly engine = "mysql";
+    private readonly _spawnSync;
+    private readonly _importMysql;
+    private readonly _platform;
+    constructor(opts?: MysqlCapabilityProbeOptions);
+    /**
+     * Run all detections (driver, CLI) and return the composite result.
+     * Any detection failure is reported as unavailable — never throws.
+     * odbc is always false for MySQL.
+     */
+    probe(): Promise<ProbeResult>;
+    /**
+     * Checks whether the 'mysql2' npm package is importable WITHOUT connecting.
+     * Resolves true on success, false on any error.
+     */
+    private _detectNativeDriver;
+    /**
+     * Scans for the mysql CLI on PATH using where (Windows) / which (POSIX).
+     * If found, parses the version from mysql --version.
+     * Always resolves with one CliToolInfo entry for 'mysql'.
+     */
+    private _detectCliTools;
+    private _detectMysqlCli;
+    /**
+     * Runs mysql --version to extract the version string.
+     * Returns null on any failure.
+     */
+    private _parseMysqlVersion;
+}
+
+/**
+ * SqliteCapabilityProbe — CapabilityProbe implementation for SQLite.
+ * Design §"probe() is OPTIONAL on the strategy port; per-engine probe in adapters".
+ * Resilient-connectivity Batch 2, task 2.4.
+ *
+ * Detection strategy:
+ *   - nativeDriver: true if better-sqlite3 OR node:sqlite is importable (no DB opened)
+ *   - cliTools:     [] (no separate CLI tool relevant to SQLite extraction)
+ *   - odbc:         always false (N/A for SQLite)
+ *
+ * Driver selection mirrors the shipped sqlite/factory.ts logic:
+ *   1. Try better-sqlite3 first (the default driver — ships as a prod dependency).
+ *   2. Fall back to node:sqlite if better-sqlite3 is absent and Node >= 22.5.
+ * The probe keeps the surface uniform: same ProbeResult shape across all four engines
+ * so `doctor` and the engine-agnostic parity suite are engine-agnostic by construction.
+ *
+ * All detection failures yield a NEGATIVE result — probe() MUST NEVER reject.
+ *
+ * Seams (all optional — omit for production use):
+ *   - importBetterSqlite: injectable import() for 'better-sqlite3'
+ *   - importNodeSqlite:   injectable import() for 'node:sqlite'
+ *
+ * ADR-004: no child_process here (no CLI tool for SQLite).
+ */
+
+/** Injectable seam for dynamic import('better-sqlite3'). */
+type ImportBetterSqliteFn = () => Promise<unknown>;
+/** Injectable seam for dynamic import('node:sqlite'). */
+type ImportNodeSqliteFn = () => Promise<unknown>;
+/**
+ * Constructor options for SqliteCapabilityProbe.
+ * All fields are optional — omit entirely for production use.
+ */
+interface SqliteCapabilityProbeOptions {
+    /** Injectable better-sqlite3 import seam. Defaults to dynamic import('better-sqlite3'). */
+    readonly importBetterSqlite?: ImportBetterSqliteFn;
+    /** Injectable node:sqlite import seam. Defaults to dynamic import('node:sqlite'). */
+    readonly importNodeSqlite?: ImportNodeSqliteFn;
+}
+/**
+ * Capability probe for SQLite.
+ * Implements CapabilityProbe — engine = 'sqlite'.
+ *
+ * probe() MUST resolve, never reject.
+ * probe() MUST NOT open a DB file.
+ * probe() MUST NOT issue any write.
+ *
+ * cliTools is always empty — there is no separate CLI tool for SQLite extraction.
+ * odbc is always false — N/A for SQLite.
+ */
+declare class SqliteCapabilityProbe implements CapabilityProbe {
+    readonly engine = "sqlite";
+    private readonly _importBetterSqlite;
+    private readonly _importNodeSqlite;
+    constructor(opts?: SqliteCapabilityProbeOptions);
+    /**
+     * Detects whether at least one SQLite driver is available.
+     * Checks better-sqlite3 first, then node:sqlite.
+     * Never opens a database file.
+     * Never throws.
+     */
+    probe(): Promise<ProbeResult>;
+    /**
+     * Returns true if better-sqlite3 or node:sqlite is importable.
+     * Tries better-sqlite3 first (it is the default and shipped prod dep).
+     * Falls back to node:sqlite if better-sqlite3 is absent.
+     * Returns false if both are absent or both throw.
+     */
+    private _detectNativeDriver;
+}
+
+/**
+ * MongodbCapabilityProbe — CapabilityProbe implementation for MongoDB.
+ * Design §"probe() NEVER rejects; per-engine probe in adapters".
+ * Mirrors PgCapabilityProbe exactly in structure.
+ *
+ * Detection strategy:
+ *   - nativeDriver: dynamic import('mongodb') resolves → present (NO MongoClient.connect())
+ *   - cliTools:     where/which mongosh on PATH (cross-platform); version via mongosh --version
+ *   - odbc:         always false (N/A for MongoDB)
+ *
+ * All detection failures, timeouts, and absent prerequisites yield a NEGATIVE
+ * result — probe() MUST NEVER reject.
+ *
+ * Seams (all optional — omit for production use):
+ *   - spawnSync:      injectable child_process.spawnSync
+ *   - importMongodb:  injectable import() for 'mongodb' (mirrors factory.ts seam)
+ *   - platform:       injectable process.platform override (for cross-platform testing)
+ *
+ * ADR-004: this file MAY import node:child_process (adapter territory).
+ * US-030 (MongoDB adapter), phase-9b-mongodb Batch 3 task 3.4.
+ */
+
+/**
+ * Injectable seam for node:child_process.spawnSync (Buffer overload).
+ * Mirrors PgCapabilityProbe seam pattern.
+ */
+type SpawnSyncFn = (command: string, args: readonly string[], options: SpawnSyncOptions) => SpawnSyncReturns<Buffer>;
+/**
+ * Injectable seam for dynamic import('mongodb').
+ * Resolves with the module when present; rejects on MODULE_NOT_FOUND.
+ * MUST NOT call MongoClient.connect() or instantiate any class.
+ */
+type ImportMongodbFn = () => Promise<unknown>;
+/**
+ * Constructor options for MongodbCapabilityProbe.
+ * All fields are optional — omit entirely for production use.
+ */
+interface MongodbCapabilityProbeOptions {
+    /** Injectable spawnSync seam. Defaults to node:child_process.spawnSync. */
+    readonly spawnSync?: SpawnSyncFn;
+    /** Injectable mongodb import seam. Defaults to dynamic import('mongodb'). */
+    readonly importMongodb?: ImportMongodbFn;
+    /** Injectable platform override for cross-platform PATH detection testing. */
+    readonly platform?: NodeJS.Platform;
+}
+/**
+ * Capability probe for MongoDB.
+ * Implements CapabilityProbe — engine = 'mongodb'.
+ *
+ * probe() MUST resolve, never reject.
+ * probe() MUST NOT open a DB connection.
+ * probe() MUST NOT issue any write.
+ */
+declare class MongodbCapabilityProbe implements CapabilityProbe {
+    readonly engine = "mongodb";
+    private readonly _spawnSync;
+    private readonly _importMongodb;
+    private readonly _platform;
+    constructor(opts?: MongodbCapabilityProbeOptions);
+    /**
+     * Run all detections (driver, CLI) and return the composite result.
+     * Any detection failure is reported as unavailable — never throws.
+     * odbc is always false for MongoDB.
+     */
+    probe(): Promise<ProbeResult>;
+    /**
+     * Checks whether the 'mongodb' npm package is importable WITHOUT connecting.
+     * Resolves true on success, false on any error.
+     */
+    private _detectNativeDriver;
+    /**
+     * Scans for mongosh on PATH using where (Windows) / which (POSIX).
+     * If found, parses the version from mongosh --version.
+     * Always resolves with one CliToolInfo entry for 'mongosh'.
+     */
+    private _detectCliTools;
+    private _detectMongosh;
+    /**
+     * Runs mongosh --version to extract the version string.
+     * Returns null on any failure.
+     */
+    private _parseMongoshVersion;
+}
+
+/**
+ * profiles.ts — SqlcmdProfile registry for SQL Server connectivity.
+ *
+ * Encodes known sqlcmd variant/version quirks as DATA, not code branches.
+ * Design Decision: "SqlcmdProfile registry is a data table in adapters".
+ * Spec (US-040): "Variant/version profile registry encodes known quirks as data".
+ *
+ * F-3: Legacy sqlcmd 15.x flag mutual-exclusivities — -y 0 used ALONE (no -h/-W).
+ * F-4: 2033-char chunk lines, NO column header, NO dashes separator.
+ * F-5: -f o:65001 forces UTF-8 stdout codepage.
+ * F-6: Reassembler must concatenate verbatim — no .trim() at chunk boundaries.
+ *
+ * Adding a new environment = adding one entry to SQLCMD_PROFILES.
+ * No transport code changes required.
+ *
+ * ADR-004: this file lives in adapters territory; it may import core ports.
+ * It MUST NOT import node:child_process or any driver.
+ */
+
+/**
+ * Profile encoding a specific sqlcmd variant+version environment.
+ *
+ * Fields:
+ *   variant      — tool variant identifier (e.g. 'legacy-odbc', 'go-sqlcmd')
+ *   versionRange — human-readable version range (e.g. '15.x', '16.x', 'any')
+ *   flags        — extra argv flags to append to the sqlcmd invocation
+ *                  (EXACT array — no -h, no -W for legacy-15.x per F-3)
+ *   outputShape  — describes the FOR JSON output format for this variant+version
+ *   encoding     — Buffer decoding encoding for stdout (e.g. 'utf8')
+ */
+interface SqlcmdProfile {
+    /** Stable tool variant identifier, e.g. 'legacy-odbc', 'go-sqlcmd'. */
+    readonly variant: string;
+    /** Human-readable version range string, e.g. '15.x'. */
+    readonly versionRange: string;
+    /**
+     * Extra argv flags to pass to sqlcmd for catalog/fingerprint invocations.
+     * For legacy-15.x: ['-y', '0', '-f', 'o:65001'] — -y 0 alone (F-3).
+     */
+    readonly flags: readonly string[];
+    /** Describes the FOR JSON output format emitted by this variant+version. */
+    readonly outputShape: {
+        /** Byte width of each FOR JSON chunk line (2033 for legacy-15.x — F-4). */
+        readonly chunkSize: number;
+        /**
+         * Whether the output has a column-header line before the JSON data.
+         * False for legacy-15.x with -y 0 and SET NOCOUNT ON (F-4).
+         */
+        readonly hasHeader: boolean;
+    };
+    /**
+     * Node.js Buffer encoding for stdout.toString().
+     * 'utf8' when -f o:65001 is in flags (F-5).
+     */
+    readonly encoding: string;
+}
+/**
+ * Resolves the SqlcmdProfile for the given probe result.
+ *
+ * Matching algorithm:
+ *   1. Extract the version string from the first sqlcmd CliToolInfo entry.
+ *   2. For each registered profile (in order), check if the version matches
+ *      the profile's versionRange (simple major-version prefix match).
+ *   3. Return the first matching profile.
+ *   4. If no entry matches → return DEFAULT_PROFILE (never throw).
+ *
+ * The conservative-default guarantee means an unrecognized environment
+ * produces a profile, not an exception (US-040 requirement).
+ */
+declare function resolveProfile(probe: ProbeResult): SqlcmdProfile;
+
+/**
+ * Truthful CapabilityMatrix for SQLite.
+ * Design §3 "CapabilityMatrix (truthful SQLite)".
+ * SQLite supports: schema, table, column, constraint, index, view, trigger.
+ * SQLite does NOT support: procedure, function, sequence, collection, field,
+ *   statistics, sampling (these concepts do not exist in SQLite).
+ * supportsBodies: true  — view + trigger SQL available from sqlite_master.
+ * supportsDependencyHints: false — the flag denotes cheap catalog hints (a dependency PRAGMA),
+ *   which SQLite does NOT expose; false here matches pg/mysql/mongodb. Dependency edges
+ *   (view depends_on, trigger writes_to/reads_from) are body-derived — parsed from the view/
+ *   trigger body SQL via the shared presence-gate tokenizer — so the flag gates no code path here.
+ */
+
+declare const SQLITE_CAPABILITIES: CapabilityMatrix;
+
+/**
+ * Truthful CapabilityMatrix for Microsoft SQL Server.
+ * Design §CapabilityMatrix "CapabilityMatrix (truthful SQL Server)".
+ *
+ * SQL Server supports: schema, table, column, constraint, index, view,
+ *   procedure, function, trigger, sequence.
+ * SQL Server does NOT support: collection, field (MongoDB-only concepts).
+ *
+ * supportsBodies: true  — sys.sql_modules.definition provides bodies
+ *   for views, procedures, functions, triggers (level-gated).
+ * supportsDependencyHints: true — sys.sql_expression_dependencies feeds the
+ *   conservative body tokenizer to classify read/write edges (US-007, ADR-007).
+ *
+ * US-027 (SQL Server adapter), E5 common criterion (truthful matrix).
+ */
+
+declare const MSSQL_CAPABILITIES: CapabilityMatrix;
+
+/**
+ * Truthful CapabilityMatrix for PostgreSQL.
+ * Design §CapabilityMatrix "Truthful PostgreSQL CapabilityMatrix".
+ *
+ * PG supports: schema, table, column, constraint, index, view,
+ *   procedure, function, trigger, sequence.
+ * PG does NOT support: collection, field (MongoDB-only concepts).
+ *
+ * supportsBodies: true  — pg_get_functiondef/pg_get_viewdef provide bodies
+ *   for views, procedures, functions, triggers (level-gated).
+ * supportsDependencyHints: false — Phase-8a derives edges from bodies ONLY
+ *   (no pg_depend OID-graph edge list; body tokenizer is the SOLE edge source).
+ *   pg_depend/pg_rewrite OID-graph mapping is recorded as a future enhancement.
+ *
+ * US-028 (PostgreSQL adapter), US-028b (matview without model change),
+ * E5 common criterion (truthful matrix).
+ */
+
+declare const PG_CAPABILITIES: CapabilityMatrix;
+
+/**
+ * Truthful CapabilityMatrix for MySQL.
+ * Design §MYSQL_CAPABILITIES.
+ *
+ * MySQL supports: table, column, constraint, index, view,
+ *   procedure, function, trigger.
+ * MySQL does NOT support: sequence (AUTO_INCREMENT is a per-table column
+ *   property, not a first-class sequence object — MYSQL_CAPABILITIES omits
+ *   'sequence'; golden asserts ZERO sequence objects).
+ * MySQL does NOT expose a standalone schema kind: the connected database IS
+ *   the namespace (schema == database), surfaced via RawCatalog.schemas.
+ *
+ * supportsBodies: true  — VIEW_DEFINITION + ROUTINE_DEFINITION provide bodies.
+ * supportsDependencyHints: false — MySQL has no information_schema dependency
+ *   view (no pg_depend / sys.sql_expression_dependencies equivalent).
+ *   The body tokenizer is the SOLE edge source.
+ *
+ * US-029 (MySQL adapter, Phase 8b), E5 common criterion (truthful matrix).
+ */
+
+declare const MYSQL_CAPABILITIES: CapabilityMatrix;
+
+/**
+ * Truthful CapabilityMatrix for MongoDB.
+ * Design §MONGODB_CAPABILITIES.
+ *
+ * MongoDB supports: collection, field, index ONLY.
+ * MongoDB does NOT support: table, column, constraint, view, procedure,
+ *   function, trigger, sequence (SQL-only concepts irrelevant to MongoDB).
+ *
+ * supportsBodies: false  — MongoDB has no procedure or view body to retrieve.
+ * supportsDependencyHints: false — the body tokenizer is the SOLE edge source.
+ *   (MongoDB has no analog to pg_depend or sys.sql_expression_dependencies.)
+ *
+ * US-030 (MongoDB adapter, Phase 9b), E5 common criterion (truthful matrix).
+ */
+
+declare const MONGODB_CAPABILITIES: CapabilityMatrix;
+
+/**
+ * Package public API — design §2.
+ * Re-exports everything from the core barrel plus the SQLite adapter factory.
+ * The adapter factory is the ONLY place core and adapters are joined (ADR-004).
+ *
+ * Consumers: import from '@niklerk23/dbgraph' — never from internal sub-paths.
+ */
+declare const DBGRAPH_VERSION = "1.0.0";
+
+/**
+ * Returns the static CapabilityMatrix for the given dialect WITHOUT opening
+ * a database connection. Unknown dialect throws UnsupportedDialectError.
+ * Design Decision 6 (phase-4-cli-config).
+ */
+declare function capabilitiesFor(dialect: string): CapabilityMatrix;
+
+export { type AdapterAndStore, type CapabilityMatrix, type CapabilityProbe, type CliToolInfo, type ColumnAnnotations, type ColumnPayload, ConfigError, ConnectionError, type ConnectivityOption, type ConnectivityOutcome, type ConnectivityStrategy, ConnectivityUnavailableError, type ConstraintPayload, DBGRAPH_VERSION, DbgraphError, type DetectResult, type DoctorView, EDGE_CONFIDENCE_VALUES, EDGE_KINDS, type EdgeAttrs, type EdgeConfidence, type EdgeKind, type ExploreDetail, type ExploreView, type ExtractionScope, type FieldPayload, type GraphEdge, type GraphNode, type GraphStore, INDEX_LEVELS, type ImpactChain, type ImpactDetail, type ImpactQuery, type ImpactResult, type ImpactView, type IndexLevel, type IndexPayload, type JoinHop, LEVENSHTEIN_THRESHOLD, type LevelResult, type Logger, MONGODB_CAPABILITIES, MSSQL_CAPABILITIES, MYSQL_CAPABILITIES, type McpStatusView, type MongodbAdapterConfig, MongodbCapabilityProbe, type MssqlAdapterConfig, MssqlCapabilityProbe, type MysqlAdapterConfig, MysqlCapabilityProbe, NODE_KINDS, type NeighborEntry, type NeighborGroups, type NeighborQuery, type NodeKind, type NodePayload, NormalizationError, type NormalizationResult, type NormalizedGraph, NotFoundError, type ObjectDetail, type ObjectTypeLevels, type ObjectView, PG_CAPABILITIES, type PathQuery, type PathResult, type PathView, PermissionError, type PgAdapterConfig, PgCapabilityProbe, type PrecheckDetail, type PrecheckImpactSection, type PrecheckItem, type PrecheckView, type ProbeResult, QueryError, type RawCatalog, type RawColumn, type RawConstraint, type RawDependency, type RawField, type RawIndex, type RawObject, type RawTriggerInfo, type RelatedDetail, type ExploreView as RelatedView, type RoutinePayload, SQLITE_CAPABILITIES, type SchemaAdapter, type SchemaAdapterConfig, SchemaVersionError, type SearchDetail, type SearchHit, type SearchQuery, type SearchResult, type SearchView, type SnapshotObjectRow, type SnapshotRecord, type SqlcmdProfile, type SqliteAdapterConfig, SqliteCapabilityProbe, type StatusDetail, StorageError, type StrategyAttempt, StrategyExhaustionError, type StubInfo, TYPO_CAP, type TablePayload, TransportError, type TriggerPayload, UnsupportedDialectError, type UpsertResult, applyLevel, canonicalQName, capabilitiesFor, createMongodbSchemaAdapter, createMssqlSchemaAdapter, createMysqlSchemaAdapter, createPgSchemaAdapter, createSqliteGraphStore, createSqliteSchemaAdapter, deriveColumnAnnotations, edgeId, extractIdentifiers, findJoinPath, formatDoctor, formatExplore, formatImpact, formatObject, formatOutcome, formatPath, formatPrecheck, formatRelated, formatSearch, formatStatus, getImpact, getNeighbors, nodeId, noopLogger, normalizeBody, normalizeCatalog, openConnections, renderColumns, renderConstraints, renderFocusPayload, renderIndexes, renderTriggers, resolveProfile, runPrecheck, search, stableStringify };