@datasynx/agentic-ai-cartography 2.0.0 → 2.3.0

package/dist/index.d.cts

@@ -1,9 +1,51 @@
 import Database from 'better-sqlite3';
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import http from 'node:http';
+import http, { IncomingMessage, Server } from 'node:http';
 import { McpServerConfig, HookCallback } from '@anthropic-ai/claude-agent-sdk';
 
+/**
+ * Topology diffing — pure, deterministic comparison of two discovery snapshots.
+ *
+ * This module knows nothing about the database; it operates on plain
+ * node/edge arrays so it can be unit-tested in isolation and reused by the
+ * CLI, the MCP server, and the exporter. Drift is detected on a stable
+ * projection of node fields (see DRIFT_FIELDS); `confidence` is reported but
+ * never on its own marks a node as changed.
+ */
+
+/** Deterministic JSON serialization with recursively sorted object keys. */
+declare function stableStringify(value: unknown): string;
+interface TopologyInput {
+    nodes: NodeRow[];
+    edges: EdgeRow[];
+}
+interface TopologyDelta {
+    nodes: {
+        added: NodeRow[];
+        removed: NodeRow[];
+        changed: NodeChange[];
+        unchanged: number;
+    };
+    edges: {
+        added: EdgeRow[];
+        removed: EdgeRow[];
+        unchanged: number;
+    };
+    summary: {
+        nodesAdded: number;
+        nodesRemoved: number;
+        nodesChanged: number;
+        edgesAdded: number;
+        edgesRemoved: number;
+    };
+}
+/**
+ * Compute the delta from `base` to `current`. Nodes are keyed by `id`, edges by
+ * (source, target, relationship). Pure: same inputs always yield the same output.
+ */
+declare function diffTopology(base: TopologyInput, current: TopologyInput): TopologyDelta;
+
 declare const NODE_TYPES: readonly ["host", "database_server", "database", "table", "web_service", "api_endpoint", "cache_server", "message_broker", "queue", "topic", "container", "pod", "k8s_cluster", "config_file", "saas_tool", "unknown"];
 type NodeType = typeof NODE_TYPES[number];
 /**
@@ -21,6 +63,22 @@ declare const NODE_TYPE_GROUPS: {
 };
 declare const EDGE_RELATIONSHIPS: readonly ["connects_to", "reads_from", "writes_to", "calls", "contains", "depends_on"];
 type EdgeRelationship = typeof EDGE_RELATIONSHIPS[number];
+/** Billing period the amount covers. Cross-period rollup is bucketed, never normalized (5.1). */
+declare const COST_PERIODS: readonly ["hourly", "daily", "monthly", "yearly"];
+type CostPeriod = typeof COST_PERIODS[number];
+/** Attributed cost for one billing period (3.3). Amount is in `currency` per `period`. */
+declare const CostEntrySchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+    period: z.ZodEnum<{
+        hourly: "hourly";
+        daily: "daily";
+        monthly: "monthly";
+        yearly: "yearly";
+    }>;
+    source: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CostEntry = z.infer<typeof CostEntrySchema>;
 declare const NodeSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodEnum<{
@@ -49,6 +107,18 @@ declare const NodeSchema: z.ZodObject<{
     domain: z.ZodOptional<z.ZodString>;
     subDomain: z.ZodOptional<z.ZodString>;
     qualityScore: z.ZodOptional<z.ZodNumber>;
+    owner: z.ZodOptional<z.ZodString>;
+    cost: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+        period: z.ZodEnum<{
+            hourly: "hourly";
+            daily: "daily";
+            monthly: "monthly";
+            yearly: "yearly";
+        }>;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 type DiscoveryNode = z.infer<typeof NodeSchema>;
 declare const EdgeSchema: z.ZodObject<{
@@ -66,6 +136,32 @@ declare const EdgeSchema: z.ZodObject<{
     confidence: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 type DiscoveryEdge = z.infer<typeof EdgeSchema>;
+/**
+ * Per-employee sharing levels, ordered most-private → least-private:
+ * - `none`       — share nothing (the opt-in default; nothing leaves the machine).
+ * - `anonymized` — pseudonymize identifying fields (host/user/path/private-IP) via
+ *                  an org-keyed, admin-reversible HMAC while preserving topology shape.
+ * - `full`       — share the raw record verbatim.
+ */
+declare const SHARING_LEVELS: readonly ["none", "anonymized", "full"];
+declare const SharingLevelSchema: z.ZodEnum<{
+    none: "none";
+    anonymized: "anonymized";
+    full: "full";
+}>;
+type SharingLevel = typeof SHARING_LEVELS[number];
+/**
+ * A resolved sharing policy: the global `defaultLevel` (the `'*'` row) plus
+ * remembered pattern overrides (glob over the node id). The most-specific
+ * matching override wins; the default applies when nothing matches.
+ */
+interface SharingPolicy {
+    defaultLevel: SharingLevel;
+    overrides: {
+        pattern: string;
+        level: SharingLevel;
+    }[];
+}
 declare const DataAssetSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -116,6 +212,13 @@ interface NodeRow extends DiscoveryNode {
     discoveredAt: string;
     depth: number;
     pathId?: string;
+    /**
+     * Org-scoped human-readable global identity (`{tenant}:{normalizedId}`); the
+     * same logical resource collapses to one `globalId` across machines (2.9).
+     */
+    globalId?: string;
+    /** Secondary dedup key (sha256 over type + name + key-meta) that catches `id` drift between machines (2.9). */
+    contentHash?: string;
 }
 interface EdgeRow extends DiscoveryEdge {
     id: string;
@@ -129,19 +232,681 @@ interface SessionRow {
     startedAt: string;
     completedAt?: string;
     config: string;
+    /** Human-friendly, deterministically-derived label (e.g. "infra+data · 42 nodes · 2026-06-11"). */
+    name?: string;
+    /** Tenant/organization partition this session belongs to. Defaults to `'local'`. */
+    tenant: string;
+    /**
+     * Source attribution captured at session creation (2.9). Local-only — these
+     * identifying fields never leave the machine; off-machine sharing (2.11) and
+     * anonymization/consent (2.10) are deferred.
+     */
+    hostname?: string;
+    user?: string;
+    machineId?: string;
+    /**
+     * Raw `--org` / `config.organization` value as supplied (provenance). The
+     * normalized form is {@link tenant} — the org-scope partition introduced by 2.8.
+     */
+    organization?: string;
+    /**
+     * ISO 8601 UTC timestamp of the last in-place rescan of this session (2.1).
+     * `undefined`/NULL until the session is rescanned via incremental discovery —
+     * the freshness signal for scheduled discovery (2.5) to build on.
+     */
+    lastScannedAt?: string;
+}
+/**
+ * One observation of a logical node from a single machine. Accumulated in the
+ * `node_contributors` table (keyed by `(global_id, machine_id)`); never anonymized
+ * in 2.9 (that is 2.10) and never transmitted off-machine in 2.9 (that is 2.11).
+ */
+interface Contributor {
+    machineId: string;
+    hostname: string;
+    user: string;
+    /** Effective org-scope of the contribution (the session's tenant). */
+    organization?: string;
+    /** ISO 8601 UTC timestamp of the contributing observation. */
+    at: string;
+    /** Confidence of the observation that produced this contribution (0–1). */
+    confidence: number;
+}
+/**
+ * Node fields whose change marks a node as `changed` in a topology diff.
+ * `confidence` is deliberately excluded — it fluctuates between scans (noise)
+ * and is reported separately as `confidenceDelta` rather than triggering drift.
+ */
+declare const DRIFT_FIELDS: readonly ["type", "name", "domain", "subDomain", "qualityScore", "metadata", "tags", "owner", "cost"];
+type DriftField = typeof DRIFT_FIELDS[number];
+interface NodeChange {
+    id: string;
+    before: NodeRow;
+    after: NodeRow;
+    /** Which of DRIFT_FIELDS differ between `before` and `after`. */
+    changedFields: DriftField[];
+    /** Informational confidence delta (after − before); does not itself trigger drift. */
+    confidenceDelta: number;
+}
+declare const ANOMALY_KINDS: readonly ["orphan", "shadow-it"];
+type AnomalyKind = typeof ANOMALY_KINDS[number];
+declare const ANOMALY_SEVERITIES: readonly ["low", "medium", "high"];
+type AnomalySeverity = typeof ANOMALY_SEVERITIES[number];
+/** A standing structural anomaly within a single topology snapshot. Deterministic. */
+interface Anomaly {
+    /** The flagged node, structured id "{type}:{id}" — never raw free-text. */
+    nodeId: string;
+    kind: AnomalyKind;
+    severity: AnomalySeverity;
+    /** Stable, human-readable explanation built only from nodeId + numeric scores. */
+    reason: string;
+}
+/** Resolved anomaly thresholds (defaults in `DEFAULT_ANOMALY_THRESHOLDS` unless overridden by config). */
+interface AnomalyThresholds {
+    /** Degree at or below which a node is a weak-link orphan candidate (0 = isolated). */
+    orphanWeakDegree: number;
+    /** Confidence (0–1) below which an undomained node is shadow-IT. */
+    shadowConfidence: number;
+    /** qualityScore (0–100) below which an undomained node is shadow-IT. */
+    shadowQuality: number;
+}
+interface AnomalyConfig extends AnomalyThresholds {
+    /** When false, the engine short-circuits to an empty array (rollback flag). */
+    enabled: boolean;
+}
+/**
+ * Default anomaly thresholds. Defined here (not in `anomaly.ts`) so `defaultConfig`
+ * can reference them without a runtime cycle; `anomaly.ts` re-exports this constant.
+ */
+declare const DEFAULT_ANOMALY_THRESHOLDS: AnomalyThresholds;
+interface TopologyDiff {
+    base: {
+        sessionId: string;
+        startedAt: string;
+        nodeCount: number;
+        edgeCount: number;
+    };
+    current: {
+        sessionId: string;
+        startedAt: string;
+        nodeCount: number;
+        edgeCount: number;
+    };
+    nodes: {
+        added: NodeRow[];
+        removed: NodeRow[];
+        changed: NodeChange[];
+        unchanged: number;
+    };
+    edges: {
+        added: EdgeRow[];
+        removed: EdgeRow[];
+        unchanged: number;
+    };
+    summary: {
+        nodesAdded: number;
+        nodesRemoved: number;
+        nodesChanged: number;
+        edgesAdded: number;
+        edgesRemoved: number;
+    };
+    /** Standing anomalies in base vs current, plus those newly appearing in current (3.6). */
+    anomalies: {
+        base: Anomaly[];
+        current: Anomaly[];
+        added: Anomaly[];
+    };
+}
+/** Severity rank, ascending. `maxSeverity` and threshold filtering rely on this order. */
+declare const SEVERITIES: readonly ["info", "warning", "critical"];
+type Severity$1 = typeof SEVERITIES[number];
+/**
+ * Free-form metadata keys (case-insensitive) whose change escalates a node-changed
+ * item to `critical`. Security-/exposure-relevant signals live only in the
+ * free-form `metadata` blob (there are no first-class security node fields).
+ */
+declare const SECURITY_METADATA_KEYS: readonly ["publicexposure", "public", "exposed", "iamrole", "role", "encryption", "encrypted", "tls", "tlsenabled", "ports", "openports", "auth", "authentication"];
+type DriftItemKind = 'node-added' | 'node-removed' | 'node-changed' | 'edge-added' | 'edge-removed';
+interface DriftAlertItem {
+    kind: DriftItemKind;
+    /** Node id, or "source -rel-> target" for edges. */
+    ref: string;
+    /** Human-readable node/edge name for display. */
+    label: string;
+    nodeType?: NodeType;
+    severity: Severity$1;
+    /** Present for node-changed; subset of DRIFT_FIELDS that differ. */
+    changedFields?: DriftField[];
+    /** Present for node-changed; metadata keys that triggered escalation. */
+    securityFields?: string[];
+}
+interface DriftAlert {
+    base: TopologyDiff['base'];
+    current: TopologyDiff['current'];
+    summary: TopologyDiff['summary'];
+    /** Overall severity = max severity across items (info when no items). */
+    severity: Severity$1;
+    items: DriftAlertItem[];
+    /** ISO-8601 UTC generation time. */
+    generatedAt: string;
+}
+/** One configured drift sink. `url` is required when `type === 'webhook'`. */
+interface DriftSinkConfig {
+    type: 'stdout' | 'webhook';
+    /** Required when type === 'webhook'. */
+    url?: string;
+    /** Optional bearer token; falls back to CARTOGRAPHY_DRIFT_TOKEN. */
+    token?: string;
+    timeoutMs?: number;
+}
+/**
+ * Opt-in drift-alerting block on {@link CartographyConfig}. Absent → the runner
+ * defaults to a single `stdout` sink at `minSeverity: 'info'` (everything stays
+ * local; no outbound traffic unless a `webhook` sink is explicitly configured).
+ */
+interface DriftConfig {
+    /** Items below this severity are dropped before dispatch. Default 'info'. */
+    minSeverity: Severity$1;
+    sinks: DriftSinkConfig[];
+}
+/** Validate an externally-supplied drift block (CLI/env/future file loader). */
+declare const DriftConfigSchema: z.ZodObject<{
+    minSeverity: z.ZodDefault<z.ZodEnum<{
+        info: "info";
+        warning: "warning";
+        critical: "critical";
+    }>>;
+    sinks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            stdout: "stdout";
+            webhook: "webhook";
+        }>;
+        url: z.ZodOptional<z.ZodString>;
+        token: z.ZodOptional<z.ZodString>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Machine-readable result formats shared by `discover` (#67) and `schedule`. */
+declare const OUTPUT_FORMATS: readonly ["text", "json", "stream-json"];
+type OutputFormat = typeof OUTPUT_FORMATS[number];
+/**
+ * A recurring-discovery schedule, read from a JSON config file. The `cron`
+ * string is a 5-field expression (min hour dom month dow) validated by
+ * `parseCron` in `schedule.ts`; the Zod schema only enforces non-emptiness so
+ * the config layer stays decoupled from the cron grammar.
+ */
+declare const ScheduleConfigSchema: z.ZodObject<{
+    cron: z.ZodString;
+    entryPoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    outputFormat: z.ZodDefault<z.ZodEnum<{
+        text: "text";
+        json: "json";
+        "stream-json": "stream-json";
+    }>>;
+    dbPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type ScheduleConfig = z.infer<typeof ScheduleConfigSchema>;
+/**
+ * Outbound central-DB connection (2.11). The first egress path Cartograph has:
+ * after a scan, consented, policy-transformed deltas are pushed to this ingest
+ * endpoint over bearer-auth HTTPS. Presence of `url` *is* the feature flag — when
+ * absent the entire sync pipeline short-circuits and nothing ever networks.
+ *
+ * `.strict()` so a typo'd key in `config.json` fails loudly. The `token` is an
+ * opaque secret (never logged, never serialized into a payload); `org` is forwarded
+ * as a header so the central side (2.12) can scope ingest by tenant.
+ */
+declare const CentralDbConfigSchema: z.ZodObject<{
+    url: z.ZodString;
+    token: z.ZodString;
+    org: z.ZodOptional<z.ZodString>;
+    batchSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+type CentralDbConfig = z.infer<typeof CentralDbConfigSchema>;
+/**
+ * Read a {@link CentralDbConfig} from environment variables
+ * (`CARTOGRAPHY_CENTRAL_URL`/`_TOKEN`/`_ORG`), letting CI / secret-managers inject
+ * the token without a file. Returns a partial — only the keys actually present —
+ * so it composes field-wise over a `config.json` block. Never throws.
+ */
+declare function centralDbFromEnv(env?: NodeJS.ProcessEnv): Partial<CentralDbConfig>;
+/**
+ * Lifecycle status of one queued share item (2.11):
+ * - `pending`   — new/unmatched, awaiting the employee's explicit review.
+ * - `approved`  — cleared to leave (by `sync review`, or auto by a remembered rule).
+ * - `shared`    — successfully pushed to the central ingest endpoint.
+ * - `withheld`  — explicitly suppressed; never leaves.
+ *
+ * The load-bearing privacy invariant: only `approved` rows are ever pushed.
+ */
+declare const PENDING_STATUSES: readonly ["pending", "approved", "shared", "withheld"];
+type PendingStatus = typeof PENDING_STATUSES[number];
+/**
+ * One row of the `pending_shares` review queue (2.11). `payload` is the *already
+ * policy-transformed* (anonymized/dropped) projection from `previewShare` — never
+ * raw node data for `anonymized`/`none` items — so what is queued is exactly what
+ * may leave. Keyed by `contentHash` (a hash of that transformed payload).
+ */
+interface PendingShareRow {
+    contentHash: string;
+    sessionId: string;
+    nodeId?: string;
+    kind: 'node' | 'edge';
+    /** Policy-transformed payload (the exact bytes a push would send). */
+    payload: unknown;
+    status: PendingStatus;
+    /** Who decided: `'user'` (interactive review) or `'rule'` (remembered policy). */
+    decidedBy?: 'user' | 'rule';
+    createdAt: string;
+    decidedAt?: string;
+    sharedAt?: string;
+}
+/**
+ * Top-level shape of a `cartography.config.json` file. `.strict()` rejects
+ * unknown keys so typos fail loudly rather than being silently ignored. WS 2.11
+ * (central-org sync) extends this same schema with a `centralDb` block.
+ */
+declare const ConfigFileSchema: z.ZodObject<{
+    schedule: z.ZodOptional<z.ZodObject<{
+        cron: z.ZodString;
+        entryPoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        outputFormat: z.ZodDefault<z.ZodEnum<{
+            text: "text";
+            json: "json";
+            "stream-json": "stream-json";
+        }>>;
+        dbPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    entryPoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dbPath: z.ZodOptional<z.ZodString>;
+    organization: z.ZodOptional<z.ZodString>;
+    centralDb: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        token: z.ZodString;
+        org: z.ZodOptional<z.ZodString>;
+        batchSize: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type ConfigFile = z.infer<typeof ConfigFileSchema>;
+/**
+ * One persisted scheduled-discovery run (2.5). Records what changed between this
+ * run's session and the prior one, with the full {@link TopologyDelta} for audit
+ * and the summary counts for fast querying. `baseSessionId` is `undefined` on the
+ * very first run (no prior topology — everything is `added`).
+ */
+interface DriftRunRow {
+    id: string;
+    sessionId: string;
+    baseSessionId?: string;
+    /** ISO 8601 UTC timestamp this run was recorded. */
+    ranAt: string;
+    summary: {
+        nodesAdded: number;
+        nodesRemoved: number;
+        nodesChanged: number;
+        edgesAdded: number;
+        edgesRemoved: number;
+    };
+    delta: TopologyDelta;
 }
+/**
+ * Agent backend selectable via `--provider` / `CARTOGRAPHY_PROVIDER`. Defined here
+ * (in the dependency-free types module) and re-exported from `providers/types.ts`
+ * so `defaultConfig` can reference it without a runtime cycle.
+ */
+type ProviderName = 'claude' | 'openai' | 'ollama';
 interface CartographyConfig {
     maxDepth: number;
     maxTurns: number;
     entryPoints: string[];
+    /** Agent backend. Defaults to `'claude'`; selected by `--provider` / `CARTOGRAPHY_PROVIDER`. */
+    provider: ProviderName;
+    /** Lead/discovery model. Back-compat alias for `models.lead` (kept in sync by defaultConfig). */
     agentModel: string;
+    /** Model roles: `lead` drives discovery, `fast` powers cheaper helper tasks (e.g. chat). */
+    models: {
+        lead: string;
+        fast: string;
+    };
     organization?: string;
     outputDir: string;
     dbPath: string;
     verbose: boolean;
+    /** Max characters of a single scan-tool response returned to the agent (guards the context window). */
+    maxToolResponseBytes: number;
+    /** Explicit allowlist of scanner plugin package names to load (opt-in / consent-first). Default `[]`. */
+    plugins: string[];
+    /**
+     * Optional recurring-discovery schedule (2.5), populated from a config file by
+     * `loadConfig`. `undefined` for every existing/CLI caller — additive only.
+     */
+    schedule?: ScheduleConfig;
+    /**
+     * Optional central-DB outbound sync target (2.11). `undefined` for every caller
+     * unless configured via `config.json` (`centralDb` block), the
+     * `CARTOGRAPHY_CENTRAL_*` env vars, or an explicit override. Absent = the sync
+     * pipeline is fully inert (no classify, no queue, no push).
+     */
+    centralDb?: CentralDbConfig;
+    /**
+     * Optional anomaly-detection thresholds (3.6). `undefined` for every existing
+     * caller — `defaultConfig` populates it from `DEFAULT_ANOMALY_THRESHOLDS`, and the
+     * engine falls back to those defaults when absent (optional-deps-degrade).
+     */
+    anomaly?: AnomalyConfig;
+    /**
+     * Optional drift-alerting block (3.1). `undefined` for every existing/CLI caller
+     * (additive only); when absent the drift runner defaults to a local `stdout` sink.
+     * No outbound traffic unless an operator configures a `webhook` sink.
+     */
+    drift?: DriftConfig;
 }
+/** Default lead (discovery) model. */
+declare const DEFAULT_LEAD_MODEL = "claude-sonnet-4-5-20250929";
+/** Default fast model for helper tasks (chat, summaries). */
+declare const DEFAULT_FAST_MODEL = "claude-haiku-4-5-20251001";
 declare function defaultConfig(overrides?: Partial<CartographyConfig>): CartographyConfig;
 
+/**
+ * Compliance scoring (3.4) — schemas + types.
+ *
+ * Rulesets are **declarative data** (a serializable `RuleCheck` expression tree)
+ * interpreted by a single trusted engine — never executable predicate code. `field`
+ * and `pattern` are closed enums, so a ruleset can neither reach arbitrary node
+ * properties nor inject a ReDoS-prone regex. Every bundled ruleset is
+ * `RulesetSchema.parse`d at module load (fail-fast on malformed data).
+ */
+
+/** Which nodes a rule applies to. Empty scope (no groups/types) = all nodes. */
+declare const RuleScopeSchema: z.ZodObject<{
+    groups: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>>;
+    types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        host: "host";
+        database_server: "database_server";
+        database: "database";
+        table: "table";
+        web_service: "web_service";
+        api_endpoint: "api_endpoint";
+        cache_server: "cache_server";
+        message_broker: "message_broker";
+        queue: "queue";
+        topic: "topic";
+        container: "container";
+        pod: "pod";
+        k8s_cluster: "k8s_cluster";
+        config_file: "config_file";
+        saas_tool: "saas_tool";
+        unknown: "unknown";
+    }>>>;
+}, z.core.$strip>;
+type RuleScope = z.infer<typeof RuleScopeSchema>;
+declare const ConditionSchema: z.ZodObject<{
+    field: z.ZodEnum<{
+        type: "type";
+        name: "name";
+        domain: "domain";
+        subDomain: "subDomain";
+        qualityScore: "qualityScore";
+        tags: "tags";
+        owner: "owner";
+        confidence: "confidence";
+        metadataKeys: "metadataKeys";
+        metadataValues: "metadataValues";
+    }>;
+    op: z.ZodEnum<{
+        includes: "includes";
+        present: "present";
+        absent: "absent";
+        lt: "lt";
+        lte: "lte";
+        gt: "gt";
+        gte: "gte";
+        eq: "eq";
+        matches: "matches";
+    }>;
+    value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    pattern: z.ZodOptional<z.ZodEnum<{
+        dsn_with_credentials: "dsn_with_credentials";
+        owner_key: "owner_key";
+        public_exposure: "public_exposure";
+    }>>;
+}, z.core.$strip>;
+type Condition = z.infer<typeof ConditionSchema>;
+/** A serializable check: a leaf Condition or an all/any/not combinator. */
+type RuleCheck = Condition | {
+    all: RuleCheck[];
+} | {
+    any: RuleCheck[];
+} | {
+    not: RuleCheck;
+};
+declare const RuleCheckSchema: z.ZodType<RuleCheck>;
+declare const SeveritySchema: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+    critical: "critical";
+}>;
+type Severity = z.infer<typeof SeveritySchema>;
+/** Severity → score weight (decision #5). */
+declare const SEVERITY_WEIGHT: Record<Severity, number>;
+declare const ComplianceRuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    control: z.ZodString;
+    framework: z.ZodEnum<{
+        CIS: "CIS";
+        SOC2: "SOC2";
+        ISO27001: "ISO27001";
+        baseline: "baseline";
+    }>;
+    title: z.ZodString;
+    severity: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>;
+    rationale: z.ZodString;
+    scope: z.ZodObject<{
+        groups: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            [x: string]: string;
+        }>>>;
+        types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            host: "host";
+            database_server: "database_server";
+            database: "database";
+            table: "table";
+            web_service: "web_service";
+            api_endpoint: "api_endpoint";
+            cache_server: "cache_server";
+            message_broker: "message_broker";
+            queue: "queue";
+            topic: "topic";
+            container: "container";
+            pod: "pod";
+            k8s_cluster: "k8s_cluster";
+            config_file: "config_file";
+            saas_tool: "saas_tool";
+            unknown: "unknown";
+        }>>>;
+    }, z.core.$strip>;
+    applicableWhen: z.ZodOptional<z.ZodType<RuleCheck, unknown, z.core.$ZodTypeInternals<RuleCheck, unknown>>>;
+    check: z.ZodType<RuleCheck, unknown, z.core.$ZodTypeInternals<RuleCheck, unknown>>;
+}, z.core.$strip>;
+type ComplianceRule = z.infer<typeof ComplianceRuleSchema>;
+declare const RulesetSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    framework: z.ZodString;
+    description: z.ZodString;
+    rules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        control: z.ZodString;
+        framework: z.ZodEnum<{
+            CIS: "CIS";
+            SOC2: "SOC2";
+            ISO27001: "ISO27001";
+            baseline: "baseline";
+        }>;
+        title: z.ZodString;
+        severity: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            critical: "critical";
+        }>;
+        rationale: z.ZodString;
+        scope: z.ZodObject<{
+            groups: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                [x: string]: string;
+            }>>>;
+            types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                host: "host";
+                database_server: "database_server";
+                database: "database";
+                table: "table";
+                web_service: "web_service";
+                api_endpoint: "api_endpoint";
+                cache_server: "cache_server";
+                message_broker: "message_broker";
+                queue: "queue";
+                topic: "topic";
+                container: "container";
+                pod: "pod";
+                k8s_cluster: "k8s_cluster";
+                config_file: "config_file";
+                saas_tool: "saas_tool";
+                unknown: "unknown";
+            }>>>;
+        }, z.core.$strip>;
+        applicableWhen: z.ZodOptional<z.ZodType<RuleCheck, unknown, z.core.$ZodTypeInternals<RuleCheck, unknown>>>;
+        check: z.ZodType<RuleCheck, unknown, z.core.$ZodTypeInternals<RuleCheck, unknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type Ruleset = z.infer<typeof RulesetSchema>;
+declare const ControlResultSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    control: z.ZodString;
+    framework: z.ZodString;
+    severity: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>;
+    status: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        not_applicable: "not_applicable";
+    }>;
+    applicableCount: z.ZodNumber;
+    passedCount: z.ZodNumber;
+    failingNodeIds: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type ControlResult = z.infer<typeof ControlResultSchema>;
+declare const ComplianceReportSchema: z.ZodObject<{
+    rulesetName: z.ZodString;
+    rulesetVersion: z.ZodString;
+    generatedAt: z.ZodString;
+    score: z.ZodNullable<z.ZodNumber>;
+    status: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        not_applicable: "not_applicable";
+    }>;
+    totals: z.ZodObject<{
+        rules: z.ZodNumber;
+        applicable: z.ZodNumber;
+        passed: z.ZodNumber;
+        failed: z.ZodNumber;
+        notApplicable: z.ZodNumber;
+    }, z.core.$strip>;
+    bySeverity: z.ZodRecord<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>, z.ZodObject<{
+        passed: z.ZodNumber;
+        failed: z.ZodNumber;
+    }, z.core.$strip>>;
+    controls: z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        control: z.ZodString;
+        framework: z.ZodString;
+        severity: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            critical: "critical";
+        }>;
+        status: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            not_applicable: "not_applicable";
+        }>;
+        applicableCount: z.ZodNumber;
+        passedCount: z.ZodNumber;
+        failingNodeIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    gaps: z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        control: z.ZodString;
+        severity: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            critical: "critical";
+        }>;
+        title: z.ZodString;
+        nodeIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ComplianceReport = z.infer<typeof ComplianceReportSchema>;
+
+/** Attribution applied by an enrichment pass (3.3). `null` clears the field; `undefined` leaves it unchanged. */
+interface NodeAttribution {
+    owner?: string | null;
+    cost?: CostEntry | null;
+}
+
+/** Default tenant for single-user / pre-migration installs. */
+declare const DEFAULT_TENANT = "local";
+/**
+ * Normalize an untrusted tenant id: strip invisible/control characters, trim,
+ * cap length, and enforce a conservative key charset. Falls back to DEFAULT_TENANT
+ * when the input is missing or invalid. The tenant is a data-scoping partition key
+ * (not an auth boundary — RBAC is Phase 4), so the rule is shared by the DB and MCP
+ * layers via this one helper.
+ */
+declare function normalizeTenant(raw?: string | null): string;
+/**
+ * Deterministic, pure normalization of a node id so the same logical resource
+ * yields the same key across machines: trim, lowercase, collapse internal
+ * whitespace, strip a single trailing default port (:80/:443).
+ */
+declare function normalizeId(id: string): string;
+/**
+ * Extract only the stable key-meta subset (`host`/`port`/`path`/`url`) from a
+ * metadata blob (pure). Never the whole blob, which carries machine-local noise
+ * such as timestamps and absolute paths.
+ */
+declare function keyMetaOf(metadata: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Secondary dedup key: sha256 over type + normalized name + sorted key-meta.
+ * Catches `id` drift between machines for the same logical resource. Truncated
+ * to 32 hex chars (128 bits) — ample for collision resistance at org scale.
+ */
+declare function contentHash(type: string, name: string, keyMeta: Record<string, unknown>): string;
+/**
+ * Human-readable primary identity: org-scoped normalized id (`{org}:{normalizedId}`).
+ * `org` is the session's normalized tenant (2.8's partition) — the `'_'` sentinel
+ * isolates org-less sessions into their own namespace so two organizations never
+ * collapse onto one logical node even with identical infra.
+ */
+declare function globalId(organization: string | undefined, id: string): string;
 interface ConnectionRow extends Connection {
     sessionId: string;
     createdAt: string;
@@ -162,7 +927,61 @@ interface GraphSummary {
         type: string;
         degree: number;
     }>;
+    /** Standing structural anomalies (orphans / shadow-IT), computed at read time (3.6). */
+    anomalies: Anomaly[];
+    /** Distinct machines that contributed to this session's nodes (2.9 attribution). */
+    contributors: number;
+    /** Cost rolled up by domain, bucketed by (currency, period) — never FX-normalized (3.3). */
+    costByDomain: Array<{
+        domain: string;
+        currency: string;
+        period: string;
+        total: number;
+        nodes: number;
+    }>;
+    /** Cost rolled up by owner, bucketed by (currency, period) (3.3). */
+    costByOwner: Array<{
+        owner: string;
+        currency: string;
+        period: string;
+        total: number;
+        nodes: number;
+    }>;
+    /** Nodes carrying a cost vs. total — attribution coverage (3.3). */
+    costCoverage: {
+        withCost: number;
+        total: number;
+    };
+}
+/**
+ * Org-wide aggregate index (2.12) — the central-collector analogue of
+ * {@link GraphSummary}. Scoped to a single tenant (`org`) rather than one session,
+ * so it merges every machine's contribution into one organization-wide topology.
+ */
+interface OrgSummary {
+    org: string;
+    totals: {
+        nodes: number;
+        edges: number;
+    };
+    nodesByType: Record<string, number>;
+    nodesByDomain: Record<string, number>;
+    edgesByRelationship: Record<string, number>;
+    topConnected: Array<{
+        id: string;
+        name: string;
+        type: string;
+        degree: number;
+    }>;
+    /** Distinct machines that contributed to this org's nodes (2.9 attribution, org-wide). */
+    contributors: number;
 }
+/**
+ * Derive a deterministic, human-friendly session label from its graph summary,
+ * e.g. `"infra+data · 42 nodes · 2026-06-11"`. Pure: same summary + timestamp
+ * always yields the same name. No LLM call.
+ */
+declare function deriveSessionName(summary: GraphSummary, startedAt: string): string;
 /** Result of a recursive dependency traversal. */
 interface TraversalResult {
     root?: NodeRow;
@@ -185,6 +1004,8 @@ interface EventRow {
     targetType?: string;
     port?: number;
     durationMs?: number;
+    command?: string;
+    resultBytes?: number;
 }
 interface TaskRow {
     id: string;
@@ -210,7 +1031,12 @@ interface WorkflowRow {
 }
 declare class CartographyDB {
     private db;
-    constructor(dbPath: string);
+    /** 3.6 anomaly settings; defaults apply when no `anomaly` config is supplied. */
+    private readonly anomalyEnabled;
+    private readonly anomalyThresholds;
+    constructor(dbPath: string, opts?: {
+        anomaly?: AnomalyConfig;
+    });
     private migrate;
     close(): void;
     /**
@@ -219,26 +1045,105 @@ declare class CartographyDB {
      * virtual table. Prefer the typed methods above for everything else.
      */
     rawConnection(): Database.Database;
-    createSession(mode: 'discover', config: CartographyConfig): string;
+    /**
+     * Create a discovery session, stamping its tenant from (in precedence order)
+     * the explicit `tenantId` arg → `config.organization` → DEFAULT_TENANT. The
+     * tenant is normalized once here; every child row written under this session
+     * inherits it via {@link tenantOf}.
+     */
+    createSession(mode: 'discover', config: CartographyConfig, tenantId?: string): string;
+    /** The tenant that owns a session (DEFAULT_TENANT if the session is unknown). */
+    private tenantOf;
     endSession(id: string): void;
     getSession(id: string): SessionRow | undefined;
-    getLatestSession(mode?: string): SessionRow | undefined;
-    getSessions(): SessionRow[];
+    /**
+     * Resolve the newest session, optionally constrained to a `mode` and/or
+     * `tenantId`. Omitting `tenantId` preserves the original (unscoped) behavior;
+     * passing one returns only that tenant's sessions, which is how the tenant
+     * boundary is enforced at session resolution.
+     */
+    getLatestSession(mode?: string, tenantId?: string): SessionRow | undefined;
+    getSessions(tenantId?: string): SessionRow[];
     private mapSession;
-    upsertNode(sessionId: string, node: DiscoveryNode, depth?: number): void;
+    /** Record that a session was (re-)scanned now (ISO 8601 UTC). */
+    touchSession(id: string): void;
+    /** Set (or clear) a session's human-friendly name. */
+    setSessionName(id: string, name: string): void;
+    /**
+     * Compare two discovery sessions and report drift (added/removed/changed nodes
+     * and added/removed edges). Read-only; no schema changes. Throws if either
+     * session id does not exist.
+     */
+    diffSessions(baseId: string, currentId: string): TopologyDiff;
+    /**
+     * Score a session against a compliance ruleset (3.4) — a thin wrapper over the
+     * pure `scoreTopology` engine (mirrors `diffSessions`). Throws only when the
+     * session id is unknown; the engine never throws on data shape.
+     */
+    scoreSession(sessionId: string, ruleset: Ruleset, opts?: {
+        now?: string;
+    }): ComplianceReport;
+    /**
+     * The most recent session of `mode` (and optionally `tenantId`) other than
+     * `excludeId`. Used by scheduled discovery to pick an unambiguous diff base
+     * (newest-first by `rowid`), avoiding the `getLatestSession` just-created-session
+     * ambiguity. Returns `undefined` when no such prior session exists.
+     */
+    getPreviousSession(excludeId: string, mode?: string, tenantId?: string): SessionRow | undefined;
+    /**
+     * Persist one scheduled-discovery drift run: the summary counts plus the full
+     * {@link TopologyDelta} (for audit/replay). Returns the generated row id.
+     * `ranAt` is stamped now (ISO 8601 UTC).
+     */
+    recordDriftRun(sessionId: string, baseSessionId: string | undefined, delta: TopologyDelta): string;
+    /** Recent drift runs, newest-first (`LIMIT`, default 50). */
+    getDriftRuns(limit?: number): DriftRunRow[];
+    /** The most recent drift run, or `undefined` when none has been recorded. */
+    getLatestDriftRun(): DriftRunRow | undefined;
+    private mapDriftRun;
+    upsertNode(sessionId: string, node: DiscoveryNode, depth?: number, attribution?: Contributor): void;
+    /** All contributors that observed a logical node, ordered by observation time. */
+    getContributors(globalId: string): Contributor[];
     getNodes(sessionId: string, opts?: {
         limit?: number;
         offset?: number;
     }): NodeRow[];
     getNodeCount(sessionId: string): number;
     private mapNode;
+    /**
+     * Update only the cost/owner of an existing node, without touching any other
+     * field (unlike upsertNode's INSERT OR REPLACE) — the idempotent enrichment
+     * primitive (3.3). `undefined` leaves a field unchanged; `null` clears it.
+     * No-op (returns false) if the node is absent. Cost is re-validated before write.
+     */
+    enrichNodeAttribution(sessionId: string, nodeId: string, attr: NodeAttribution): boolean;
     deleteNode(sessionId: string, nodeId: string): void;
     insertEdge(sessionId: string, edge: DiscoveryEdge): void;
+    /**
+     * Delete every edge matching the logical key (source, target, relationship)
+     * within a session. `insertEdge` writes a random PK, so logical identity is the
+     * only way to prune an edge that disappeared while both endpoints survived.
+     */
+    deleteEdgeByKey(sessionId: string, sourceId: string, targetId: string, relationship: string): void;
+    /**
+     * Apply a precomputed {@link TopologyDelta} to one session in a single
+     * transaction (2.1 incremental discovery): prune removed nodes (cascading their
+     * edges via {@link deleteNode}), upsert added/changed nodes, delete removed edges
+     * by logical key, insert added edges, and stamp `last_scanned_at`. Unchanged rows
+     * are left untouched (stable `discovered_at`).
+     *
+     * `attribution` (2.9) is forwarded to every added/changed node's upsert so a
+     * rescan keeps/appends the running machine's contributor instead of leaving it
+     * out. Unchanged nodes are not re-upserted, so their existing contributors
+     * survive the rescan. `NodeRow extends DiscoveryNode`, so the delta rows pass
+     * straight into `upsertNode` with no mapper.
+     */
+    applyTopologyDelta(sessionId: string, delta: TopologyDelta, attribution?: Contributor): void;
     getEdges(sessionId: string, opts?: {
         limit?: number;
         offset?: number;
     }): EdgeRow[];
-    insertEvent(sessionId: string, event: Pick<EventRow, 'eventType' | 'process' | 'pid' | 'target' | 'targetType' | 'port'>, taskId?: string): void;
+    insertEvent(sessionId: string, event: Pick<EventRow, 'eventType' | 'process' | 'pid' | 'target' | 'targetType' | 'port'> & Partial<Pick<EventRow, 'command' | 'resultBytes'>>, taskId?: string): void;
     getEvents(sessionId: string, since?: string): EventRow[];
     startTask(sessionId: string, description?: string): string;
     endCurrentTask(sessionId: string): void;
@@ -253,6 +1158,63 @@ declare class CartographyDB {
     deleteConnection(sessionId: string, connectionId: string): void;
     setApproval(pattern: string, action: 'save' | 'ignore' | 'auto'): void;
     getApproval(pattern: string): string | undefined;
+    /**
+     * Set (or replace) the sharing level for a pattern. The `'*'` pattern is the
+     * global default; any other pattern is an override (glob over the node id).
+     * Validated via {@link SharingLevelSchema} before write; `created_at` is ISO UTC.
+     */
+    setSharingLevel(pattern: string, level: SharingLevel): void;
+    /**
+     * The full sharing policy: the `'*'` row resolves to `defaultLevel` (`'none'`
+     * when absent — the opt-in floor), every other row becomes an override. The
+     * glob-precedence resolution itself lives in `src/sharing.ts` so it is unit
+     * testable in isolation; this returns the raw policy it consumes.
+     */
+    getSharingPolicy(): SharingPolicy;
+    /** Remove a pattern override. The global default (`'*'`) cannot be cleared this way. */
+    clearSharingOverride(pattern: string): void;
+    /**
+     * Persist the encrypted plaintext behind a pseudonym token. Idempotent: the
+     * token is deterministic, so repeated writes `INSERT OR REPLACE` and never grow
+     * the table. `ciphertext` is base64(iv ‖ tag ‖ AES-256-GCM(plaintext)).
+     */
+    saveReversal(token: string, ciphertext: string): void;
+    /** Read the stored ciphertext for a pseudonym token (admin reversal path). */
+    getReversal(token: string): string | undefined;
+    /**
+     * Enqueue one proposed share item. Idempotent via `INSERT OR IGNORE` on the
+     * `content_hash` PK: re-classifying the same (transformed) item never duplicates
+     * a row nor resets an existing decision. `payload` is the already-policy-
+     * transformed projection (the exact bytes a push would send) — never raw node
+     * data for `anonymized`/`none` items.
+     */
+    enqueuePending(item: {
+        contentHash: string;
+        sessionId: string;
+        nodeId?: string;
+        kind: 'node' | 'edge';
+        payload: unknown;
+        status: PendingStatus;
+        decidedBy?: 'user' | 'rule';
+    }): void;
+    /** Queued share items, optionally filtered by status and/or session. */
+    getPendingShares(filter?: {
+        status?: PendingStatus;
+        sessionId?: string;
+    }): PendingShareRow[];
+    /** Queue size by status (every status key present, zero-filled). */
+    countPendingByStatus(): Record<PendingStatus, number>;
+    /** `content_hash` values already pushed (status `shared`) — for re-share suppression. */
+    getSharedHashes(): Set<string>;
+    /**
+     * Transition one queued item. Stamps `decided_at` on any non-`pending` status and
+     * `shared_at` when moving to `shared`. `decidedBy` records the actor (`'user'` or
+     * `'rule'`) for the audit trail.
+     */
+    setPendingStatus(contentHash: string, status: PendingStatus, decidedBy?: 'user' | 'rule'): void;
+    /** Approved items cleared to push (FIFO), optionally capped by `limit`. */
+    getApprovedShares(limit?: number): PendingShareRow[];
+    private mapPendingShare;
     /**
      * Delete a session and all its associated data (nodes, edges, events, tasks, workflows, connections).
      */
@@ -286,6 +1248,55 @@ declare class CartographyDB {
     }): TraversalResult;
     /** Lightweight aggregate index of the whole topology — the progressive-disclosure summary. */
     getGraphSummary(sessionId: string): GraphSummary;
+    /**
+     * Resolve (creating once) the synthetic collector session that owns every
+     * central node/edge for a tenant. Central nodes are merged by `(org, global_id)`,
+     * not by session, so they live under a single deterministic session id
+     * (`central:{org}`) — this satisfies the existing `(id, session_id)` node PK and
+     * the `session_id` foreign key without a destructive schema change. Idempotent.
+     */
+    ensureCentralSession(org: string): string;
+    /**
+     * Find an existing central node within a tenant by its primary identity
+     * (`global_id`), returning its stored `id` so a merge keeps a single row.
+     */
+    findCentralNodeIdByGlobalId(org: string, gid: string): string | undefined;
+    /**
+     * Secondary merge lookup: an existing central node in the tenant whose
+     * `content_hash` matches (catches `id` drift between machines for the same
+     * logical resource). Returns its stored `id` and `global_id`.
+     */
+    findCentralNodeByContentHash(org: string, ch: string): {
+        id: string;
+        globalId: string;
+    } | undefined;
+    /**
+     * Merge one incoming node into the central store for a tenant and append the
+     * contributor (2.12). Resolves identity by `(tenant, global_id)` primary, then
+     * `(tenant, content_hash)` secondary; on a hit it keeps the existing row's id
+     * (so the logical node stays a single row), unions tags, keeps the higher
+     * confidence, and merges metadata (incoming values win on key conflict). The
+     * incoming `globalId`/`contentHash` are precomputed by the merge core so they
+     * are consistent with what the lookups used. Returns whether a new row was
+     * created or an existing one was merged. Runs in one transaction.
+     */
+    upsertCentralNode(org: string, node: DiscoveryNode, identity: {
+        globalId: string;
+        contentHash: string;
+    }, contributor: Contributor): 'created' | 'merged';
+    /** Insert an edge into the central store for a tenant (idempotent on logical key). */
+    insertCentralEdge(org: string, edge: DiscoveryEdge): void;
+    /** A central node by tenant + stored id (the merge target after identity resolution). */
+    getCentralNode(org: string, sessionId: string, nodeId: string): NodeRow | undefined;
+    /** All contributors for a logical (global_id) node across an org. */
+    getContributorsByGlobalId(gid: string): Contributor[];
+    /**
+     * Org-wide aggregate summary (2.12) — the central analogue of
+     * {@link getGraphSummary}, scoped `WHERE tenant = ?` so it merges every machine's
+     * contribution into one organization-wide view. Cross-tenant isolation is
+     * structural: org A's rows never appear in org B's counts.
+     */
+    getOrgSummary(org: string): OrgSummary;
     getStats(sessionId: string): {
         nodes: number;
         edges: number;
@@ -295,78 +1306,557 @@ declare class CartographyDB {
 }
 
 /**
- * The Cartography MCP server — the package's primary, LLM-agnostic interface.
+ * `StoreBackend` — the persistence seam for the central collector (2.12).
  *
- * It exposes the discovered infrastructure topology as Model Context Protocol
- * **Resources** (read-only context, progressive disclosure), a small set of query
- * **Tools** (parameterized lookups), and reusable **Prompts**. Any MCP host —
- * Claude Code, Cursor, Cline, Windsurf, the Vercel AI SDK, LangGraph — can drive
- * it; the package never needs to know which model is in use.
+ * The central collector merges consented discovery deltas from many machines into
+ * one organization-wide, tenant-partitioned topology. Today there is exactly one
+ * shipping implementation, {@link SqliteStoreBackend}, which wraps the existing
+ * `CartographyDB`. The interface exists so a graph/Postgres backend (4.3) can be
+ * dropped in without touching the ingest orchestration — the ingest core
+ * (`src/central/ingest.ts`) talks only to this interface, never to SQLite directly.
+ *
+ * The contract is deliberately minimal: an org-scoped node upsert (merge-by-identity
+ * with contributor attribution), an org-scoped edge insert, an org-wide summary, and
+ * a contributor read for audit/tests. Every method is tenant-scoped by `org` — there
+ * is no un-scoped path, so cross-tenant isolation is structural.
  */
 
-/** A pluggable search backend; defaults to lexical search, can be upgraded to semantic. */
-type SearchFn = (db: CartographyDB, sessionId: string, query: string, opts: {
-    types?: readonly string[];
-    limit: number;
-}) => Promise<Array<{
-    node: NodeRow;
-    score?: number;
-}>>;
-/** A pluggable discovery backend invoked by the `run_discovery` tool. */
-type DiscoveryFn = (db: CartographyDB, sessionId: string, opts: {
-    hint?: string;
-}) => Promise<{
-    nodes: number;
-    edges: number;
-}>;
-interface CreateMcpServerOptions {
-    /** Database instance. If omitted, one is opened at `config.dbPath`. */
-    db?: CartographyDB;
-    /** Path to the SQLite catalog (used when `db` is not provided). */
-    dbPath?: string;
-    /** Session to serve: a session id, or `'latest'` (default) for the newest discovery. */
-    session?: string | 'latest';
-    /** Semantic/lexical search backend. Defaults to lexical `searchNodes`. */
-    search?: SearchFn;
-    /** Discovery backend for `run_discovery`/`refresh`. Optional. */
-    discovery?: DiscoveryFn;
+/** Precomputed merge identity for an incoming node (from the merge core). */
+interface NodeIdentity {
+    /** Primary merge key — org-scoped normalized id (`{org}:{normalizedId}`). */
+    globalId: string;
+    /** Secondary merge key — content hash that catches `id` drift between machines. */
+    contentHash: string;
 }
 /**
- * Build a fully-configured Cartography MCP server. Call `.connect(transport)` to run it.
+ * A provider-agnostic central store. All operations are scoped to a single tenant
+ * (`org`); there is no cross-tenant read or write path.
  */
-declare function createMcpServer(opts?: CreateMcpServerOptions): McpServer;
+interface StoreBackend {
+    /**
+     * Merge one incoming node under `org`, keyed by `identity.globalId` (primary) then
+     * `identity.contentHash` (secondary), and append/update the `contributor`. Returns
+     * `'created'` when this is the first observation of the logical node, `'merged'`
+     * when it collapsed onto an existing one.
+     */
+    upsertNode(org: string, node: DiscoveryNode, identity: NodeIdentity, contributor: Contributor): 'created' | 'merged';
+    /** Insert an edge under `org` (idempotent on the logical `(source, target, relationship)` key). */
+    insertEdge(org: string, edge: DiscoveryEdge): void;
+    /** Org-wide aggregate summary (merged counts across all contributors). */
+    getSummary(org: string): OrgSummary;
+    /** Contributors for a merged logical node (test/audit helper). */
+    getContributors(globalId: string): Contributor[];
+    /** Release any underlying resources. */
+    close(): void;
+}
 
 /**
- * Transport bindings for the Cartography MCP server.
+ * `SqliteStoreBackend` — the default (and currently only) {@link StoreBackend}
+ * implementation for the central collector (2.12).
  *
- * - **stdio**: the local-first default — zero network, every client supports it.
- * - **Streamable HTTP**: a single `/mcp` endpoint for team/remote use, bound to
- *   localhost with DNS-rebinding protection. The deprecated SSE transport is not used.
+ * It is a thin adapter over `CartographyDB`: the schema, migrations, and merge SQL
+ * all live in `src/db.ts` (the single owner of the catalog), so this class only
+ * forwards the org-scoped central operations. Constructing it adds no new state and
+ * no new schema — the zero-config local SQLite path is byte-for-byte unchanged.
+ *
+ * A graph/Postgres backend (4.3) implements the same interface without changing the
+ * ingest orchestration that consumes it.
  */
 
-/** Connect a server over stdio (resolves when the transport closes). */
-declare function runStdio(server: McpServer): Promise<void>;
-interface HttpOptions {
-    port?: number;
-    host?: string;
-    /** Extra allowed Host headers (defaults to localhost:port variants). */
-    allowedHosts?: string[];
-    /** Allowed Origin headers (defaults to none → same-origin only). */
-    allowedOrigins?: string[];
+declare class SqliteStoreBackend implements StoreBackend {
+    private readonly db;
+    constructor(db: CartographyDB);
+    upsertNode(org: string, node: DiscoveryNode, identity: NodeIdentity, contributor: Contributor): 'created' | 'merged';
+    insertEdge(org: string, edge: DiscoveryEdge): void;
+    getSummary(org: string): OrgSummary;
+    getContributors(globalId: string): Contributor[];
+    /**
+     * No-op: the wrapped `CartographyDB` is owned by the caller (it is shared with the
+     * read-side MCP server in server-mode), so the backend never closes it. The caller
+     * closes the `CartographyDB` directly.
+     */
+    close(): void;
 }
+
 /**
- * Start a Streamable HTTP server. A fresh MCP server instance is created per
- * session via `factory`, so multiple clients can connect concurrently.
+ * `QueryBackend` — the **read-only** query seam for the API server (4.2).
+ *
+ * This is deliberately distinct from {@link StoreBackend} (`src/store/backend.ts`),
+ * which is the central-collector **write/ingest** seam. The two seams have opposite
+ * shapes: ingest merges incoming deltas; this one answers topology questions. A
+ * non-SQLite backend (4.3) implements both. Keeping them separate means the API
+ * never gains a write path and the ingest core never gains a query path.
+ *
+ * Every method takes a {@link TenantContext}. Session resolution is tenant-scoped, so
+ * a caller bound to tenant A can never read tenant B's topology — even by naming a
+ * session id that belongs to B (it resolves to "not found", never B's data). This
+ * mirrors the MCP server's `resolveSession` tenant guard exactly.
  */
-declare function runHttp(factory: () => McpServer, opts?: HttpOptions): Promise<http.Server>;
+
+/** The tenant (org-scope) a request is bound to. `'local'` (DEFAULT_TENANT) until a real org is supplied. */
+interface TenantContext {
+    tenant: string;
+}
+interface NodeQuery {
+    search?: string;
+    types?: readonly string[];
+    limit?: number;
+    offset?: number;
+}
+interface DependencyQuery {
+    direction?: 'downstream' | 'upstream' | 'both';
+    maxDepth?: number;
+}
+interface NodesResult {
+    nodes: NodeRow[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface HealthResult {
+    store: 'sqlite';
+    sessions: number;
+}
+/** A requested resource (session / diff endpoint) does not exist for this tenant → REST 404. */
+declare class NotFoundError extends Error {
+    constructor(message: string);
+}
+/** Narrow, read-only view of the topology store. Tenant is required on every call. */
+interface QueryBackend {
+    /** Aggregate, low-token index of the resolved session. Throws {@link NotFoundError} if no session resolves. */
+    summary(ctx: TenantContext, sessionId?: string): GraphSummary;
+    /** Page/search nodes of the resolved session. Throws {@link NotFoundError} if no session resolves. */
+    nodes(ctx: TenantContext, q: NodeQuery, sessionId?: string): NodesResult;
+    /** One node by id (or `undefined` if absent). Throws {@link NotFoundError} if no session resolves. */
+    node(ctx: TenantContext, id: string, sessionId?: string): NodeRow | undefined;
+    /** Dependency traversal from a node. Throws {@link NotFoundError} if no session resolves. */
+    dependencies(ctx: TenantContext, id: string, q: DependencyQuery, sessionId?: string): TraversalResult;
+    /** Compare two sessions (both must belong to the tenant). Throws {@link NotFoundError} on an unknown/foreign id. */
+    diff(ctx: TenantContext, base: string, current: string): TopologyDiff;
+    /** All sessions for this tenant, newest first. */
+    sessions(ctx: TenantContext): SessionRow[];
+    /** Liveness/coverage probe (never resolves a session). */
+    health(ctx: TenantContext): HealthResult;
+}
+/**
+ * `QueryBackend` over the local `CartographyDB`. A thin read adapter: the schema,
+ * migrations, and SQL all live in `db.ts`; this only resolves the tenant-scoped
+ * session and forwards. Constructing it adds no state and no schema.
+ */
+declare class SqliteQueryBackend implements QueryBackend {
+    private readonly db;
+    private readonly defaultSession;
+    constructor(db: CartographyDB, defaultSession?: string | 'latest');
+    /**
+     * Resolve the session id for a request, scoped to `ctx.tenant`. An explicit id must
+     * belong to the tenant or it resolves to undefined (cross-tenant isolation); else the
+     * newest `discover` session for the tenant. Mirrors `resolveSession` in the MCP server.
+     */
+    private resolveSession;
+    summary(ctx: TenantContext, sessionId?: string): GraphSummary;
+    nodes(ctx: TenantContext, q: NodeQuery, sessionId?: string): NodesResult;
+    node(ctx: TenantContext, id: string, sessionId?: string): NodeRow | undefined;
+    dependencies(ctx: TenantContext, id: string, q: DependencyQuery, sessionId?: string): TraversalResult;
+    diff(ctx: TenantContext, base: string, current: string): TopologyDiff;
+    sessions(ctx: TenantContext): SessionRow[];
+    health(ctx: TenantContext): HealthResult;
+}
+/** Construct the default SQLite-backed read query backend. */
+declare function createSqliteQueryBackend(db: CartographyDB, defaultSession?: string | 'latest'): QueryBackend;
+
+/**
+ * Global-identity merge core for the central collector (2.12) — pure, no I/O.
+ *
+ * The merge *keys* (`normalizeId`, `contentHash`, `keyMetaOf`, `globalId`) already
+ * exist in `src/db.ts` from the 2.9 identity work; this module re-exports them so
+ * the central collector has one import surface, and adds {@link computeIdentity} —
+ * the small adapter that turns one incoming `DiscoveryNode` into the precomputed
+ * `(globalId, contentHash)` pair the {@link StoreBackend} merge consumes.
+ *
+ * The merge *resolution* (primary by `(org, globalId)`, secondary by
+ * `(org, contentHash)`, contributor union, max-confidence) lives in the store
+ * (`CartographyDB.upsertCentralNode`) because it needs the existing row — keeping
+ * the SQL next to the schema. This module is the deterministic key derivation that
+ * both the client (push) and the server (ingest) must agree on.
+ */
+
+/**
+ * Derive the precomputed merge identity for one incoming node under `org`:
+ * - `globalId` = `{org}:{normalizeId(node.id)}` (primary key; the org-scope ensures
+ *   two organizations never collapse onto one logical node).
+ * - `contentHash` = sha256 over `type + normalized name + sorted key-meta` (secondary
+ *   key; catches `id` drift between machines for the same logical resource).
+ *
+ * Pure and deterministic: the same node + org always yields the same identity, on
+ * any machine. This is the contract the client (2.11 push) and the server (ingest)
+ * share so a content hash computed on the client matches the one the server recomputes.
+ */
+declare function computeIdentity(org: string, node: DiscoveryNode): NodeIdentity;
+
+/**
+ * Server-side anonymization re-validation for the central collector (2.12).
+ *
+ * **Don't trust the client.** The client (2.10) is supposed to pseudonymize
+ * identifying fragments before pushing at the `anonymized` sharing level, but the
+ * collector independently re-checks every incoming payload and rejects or scrubs any
+ * un-anonymized identifying fragment it finds. This is defense-in-depth: a buggy,
+ * outdated, or malicious client cannot leak raw identifiers into the org-wide store.
+ *
+ * The walker mirrors `redactValue`/`pseudonymize` (it rewrites only leaf strings;
+ * structure is invariant). What it flags at the `anonymized` level:
+ *  - **private-ip**   — RFC-1918 / loopback IPv4 (`src/anonymize.ts:PRIVATE_IP` + 127/8).
+ *  - **absolute-path**— POSIX (`/home/alice/...`) or Windows (`C:\Users\alice\...`) paths.
+ *  - **username**     — the user segment of `/home/<u>`, `/Users/<u>`, `C:\Users\<u>`.
+ *  - **hostname**     — multi-label FQDNs (`db-01.internal.acme.lan`), AND the known
+ *    2.10 residual: **bare single-label internal hostnames** (e.g. `db-prod-01`) that
+ *    the client's multi-label-only HOSTNAME regex never tokenizes. A token already in
+ *    `anon:{kind}:{base32}` form is recognized as anonymized and never flagged.
+ *
+ * At the `none` / `full` levels nothing is claimed to be anonymized, so re-validation
+ * is a no-op (returns no violations): the employee consented to share at that level.
+ */
+
+/** The anonymization level claimed by an ingest envelope (mirrors `SharingLevel`). */
+type AnonymizationLevel = 'none' | 'anonymized' | 'full';
+/** A detected un-anonymized identifying fragment, with its location for logging. */
+interface AnonViolation {
+    /** JSON path to the offending leaf, e.g. `metadata.host`. */
+    path: string;
+    kind: 'hostname' | 'username' | 'absolute-path' | 'private-ip';
+}
+/**
+ * Recursively collect every anonymization violation in a value at the given level.
+ * Pure. At `none`/`full` returns `[]` (no anonymization is claimed). Object keys are
+ * schema, not data, so only values are inspected; `path` accumulates the location.
+ */
+declare function findAnonViolations(value: unknown, level: AnonymizationLevel, path?: string): AnonViolation[];
+/**
+ * Re-validate one node against its claimed anonymization level (2.12).
+ *
+ * - `mode: 'reject'` (default, strict) — returns the node unchanged plus the
+ *   violations; the caller drops a node with any violation and never persists it.
+ * - `mode: 'strip'` (lenient) — returns a sanitized node (offending leaves masked to
+ *   `***`) plus the violations (for logging), so the topology shape survives while
+ *   the identifying fragments do not.
+ *
+ * Pure: no I/O, no logging (the caller logs). At `none`/`full` it is a pass-through.
+ */
+declare function revalidateAnonymized(node: DiscoveryNode, level: AnonymizationLevel, mode: 'reject' | 'strip'): {
+    node: DiscoveryNode;
+    violations: AnonViolation[];
+};
+
+/**
+ * Ingest orchestration for the central collector (2.12).
+ *
+ * Consumes the 2.11 PUSH ENVELOPE verbatim —
+ *   `{ schemaVersion: 1, org?, items: [{ contentHash, kind: 'node'|'edge', payload }] }`
+ * — and merges it into the tenant-partitioned central store. The pipeline is:
+ *
+ *   1. **Validate** the envelope shape (zod). A malformed envelope is rejected whole;
+ *      nothing is persisted (the HTTP layer turns this into a 400).
+ *   2. **Re-validate anonymization** per node (`revalidateAnonymized`) — the client is
+ *      not trusted. In `reject` mode a node with any identifying fragment is dropped
+ *      and counted; in `strip` mode it is scrubbed and persisted. Either way a
+ *      structured WARN is logged with the violation path + action.
+ *   3. **Merge** each node by `(org, globalId)` primary + `(org, contentHash)` secondary
+ *      with a contributor union (`store.upsertNode`), and insert edges (`store.insertEdge`)
+ *      only when both endpoints survived re-validation.
+ *   4. **Log** one structured INFO with the per-ingest counts.
+ *
+ * The contributor `at` is stamped server-side (`new Date().toISOString()`) — never
+ * trusted from the client. The envelope MAY carry a `contributor`/`anonymizationLevel`
+ * extension (2.9/2.10); absent, the collector derives a conservative default and
+ * re-validates at the `anonymized` level (the safe assumption).
+ */
+
+/** Wire-format version this collector accepts (the 2.11 `PUSH_SCHEMA_VERSION`). */
+declare const INGEST_SCHEMA_VERSION: 1;
+/**
+ * The ingest envelope — the 2.11 push contract, plus optional `contributor` /
+ * `anonymizationLevel` extension fields (read when present; never required). `org`
+ * is optional in the wire format; the collector falls back to its `defaultOrg`.
+ */
+declare const IngestEnvelopeSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    org: z.ZodOptional<z.ZodString>;
+    items: z.ZodArray<z.ZodObject<{
+        contentHash: z.ZodString;
+        kind: z.ZodEnum<{
+            node: "node";
+            edge: "edge";
+        }>;
+        payload: z.ZodUnknown;
+    }, z.core.$strip>>;
+    contributor: z.ZodOptional<z.ZodObject<{
+        machineId: z.ZodString;
+        hostname: z.ZodDefault<z.ZodString>;
+        user: z.ZodDefault<z.ZodString>;
+        confidence: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    anonymizationLevel: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        anonymized: "anonymized";
+        full: "full";
+    }>>;
+}, z.core.$strip>;
+type IngestEnvelope = z.infer<typeof IngestEnvelopeSchema>;
+/** Per-ingest outcome counts (the 200 response body). */
+interface IngestResult {
+    org: string;
+    /** Nodes persisted (created + merged). */
+    accepted: number;
+    /** Nodes that collapsed onto an existing logical node. */
+    merged: number;
+    /** Nodes dropped for anonymization violations (reject mode). */
+    rejected: number;
+    /** Edges persisted. */
+    edges: number;
+    /** Total anonymization violations detected across all nodes. */
+    violations: number;
+}
+interface IngestOptions {
+    /** `reject` (default) drops nodes with violations; `strip` scrubs and keeps them. */
+    anonMode?: 'reject' | 'strip';
+    /** Tenant used when the envelope omits `org`. */
+    defaultOrg?: string;
+}
+/**
+ * Ingest one validated envelope into the store. Returns the outcome counts.
+ * The caller (HTTP handler) wraps this in try/catch; the store's per-node upsert is
+ * itself transactional, so a single bad node never half-writes a row.
+ */
+declare function ingestEnvelope(store: StoreBackend, envelope: IngestEnvelope, opts?: IngestOptions): IngestResult;
+
+/**
+ * The central-collector ingest HTTP surface (2.12).
+ *
+ * {@link createIngestHandler} produces the request handler that the Streamable-HTTP
+ * transport mounts at `POST /ingest` when server-mode is on. It is deliberately a
+ * pure `(body) => { status, body }` function with no socket of its own, so it can be
+ * unit-tested directly without binding a port (the transport owns auth, the
+ * non-loopback host allowlist, and the body size cap — see `src/mcp/transports.ts`).
+ *
+ * Validation is fail-closed: a malformed envelope yields 400 (no writes); an internal
+ * error yields 500; only a valid envelope runs `ingestEnvelope` and returns 200 with
+ * the {@link IngestResult}. The bearer token is enforced by the transport before this
+ * handler ever runs, so the handler never sees (and never logs) the token.
+ */
+
+/** A transport-agnostic HTTP-ish response: a status code and a JSON-serializable body. */
+interface IngestResponse {
+    status: number;
+    body: unknown;
+}
+type IngestHandler = (body: unknown) => IngestResponse;
+/**
+ * Build the `/ingest` handler over a {@link StoreBackend}. The handler validates the
+ * 2.11 push envelope, runs ingest (re-validating anonymization first), and maps the
+ * outcome to an HTTP status:
+ *  - 400 — envelope failed `IngestEnvelopeSchema` (no writes).
+ *  - 500 — ingest threw (the store's per-node transaction rolls that node back).
+ *  - 200 — {@link IngestResult}.
+ */
+declare function createIngestHandler(store: StoreBackend, opts?: IngestOptions): IngestHandler;
+
+/**
+ * Org-key lifecycle for the 2.10 anonymization layer.
+ *
+ * The org key is the single secret that makes pseudonyms deterministic across
+ * machines (so a central merge collapses the same host to one token) and
+ * admin-reversible (only the key holder can invert a pseudonym). It lives on disk
+ * at `~/.cartography/org-key` (mode 0600), **never** in the SQLite catalog, never
+ * in any log line, and never in an export. The returned key is HKDF-namespaced by
+ * `organization`, so two organizations sharing one machine derive non-colliding
+ * keys (and therefore non-colliding tokens + isolated reversal maps).
+ *
+ * Zero new dependencies: HMAC/AES/HKDF/randomBytes all come from `node:crypto`.
+ */
+interface OrgKeyOptions {
+    /** Organization namespace; absent ⇒ the `'default'` namespace. */
+    organization?: string;
+    /** Override the on-disk key path (tests / non-default data dirs). */
+    keyPath?: string;
+}
+/** Default org-key file path: `~/.cartography/org-key`. */
+declare function orgKeyPath(home?: string): string;
+/**
+ * Load (or lazily create) the org key, HKDF-namespaced by `organization`. The
+ * on-disk secret is a single random value; per-org keys are derived from it so
+ * the same file serves multiple orgs without collision. Pure of side effects
+ * beyond the lazy file creation; never logs the key material.
+ */
+declare function loadOrgKey(opts?: OrgKeyOptions): Buffer;
+/**
+ * Rotate the org key: overwrite the on-disk secret with fresh random bytes and
+ * return the new derived key. Reversal entries written under the old key become
+ * unrecoverable by design — callers are warned at the stderr level.
+ */
+declare function rotateOrgKey(opts?: OrgKeyOptions): Buffer;
+/** Subkey for HMAC pseudonym tokens (distinct domain from the reversal cipher key). */
+declare function hmacKey(orgKey: Buffer): Buffer;
+/** Subkey for AES-256-GCM reversal-map encryption (distinct domain from the HMAC key). */
+declare function reversalKey(orgKey: Buffer): Buffer;
+
+/**
+ * Org-keyed, admin-reversible pseudonymization (2.10 `anonymized` sharing level).
+ *
+ * Identifying fragments — private IPs, file paths, `user@host` pairs, and bare
+ * hostnames — are replaced by a deterministic token
+ *   `anon:{kind}:{base32(first 12 bytes of HMAC-SHA256(hmacKey, plaintext))}`
+ * so the same input + org key always yields the same token (a central merge then
+ * collapses the same host across machines). The token is one-way for anyone
+ * without the org key (HMAC preimage resistance + a 32-byte secret); an admin
+ * holding the key can invert it via an AES-256-GCM reversal map.
+ *
+ * Topology shape is preserved: {@link pseudonymize} mirrors `redactValue`
+ * (`src/tools.ts`) — it walks structure, rewriting only leaf strings; it never
+ * adds, removes, or reorders keys/array elements.
+ *
+ * Zero new dependencies — all crypto is `node:crypto`.
+ */
+
+/** The kinds of identifying fragment we tokenize. The prefix keeps namespaces legible + non-colliding. */
+type FragmentKind = 'host' | 'user' | 'path' | 'ip';
+/**
+ * RFC-1918 private IPv4 ranges: 10/8, 172.16/12, 192.168/16. Only private IPs are
+ * pseudonymized — public IPs are not identifying of an employee's machine and are
+ * left intact (so topology against public infra still reads).
+ */
+declare const PRIVATE_IP: RegExp;
+/**
+ * Deterministic token for one identifying fragment. When `db` is supplied, the
+ * plaintext is AES-256-GCM-encrypted under `reversalKey(orgKey)` and persisted so
+ * an admin can later invert the token. Idempotent: the token is deterministic, so
+ * re-encrypting the same fragment `INSERT OR REPLACE`s the same row.
+ */
+declare function pseudonymizeFragment(plaintext: string, kind: FragmentKind, orgKey: Buffer, db?: CartographyDB): string;
+/**
+ * Pseudonymize the identifying fragments inside a single string — private IPs,
+ * file paths, `user@host` pairs, and bare hostnames — leaving structure-irrelevant
+ * text intact. Order matters: paths and IPs are matched before hostnames so an IP
+ * or a path segment is never mis-tokenized as a host.
+ */
+declare function pseudonymizeString(s: string, orgKey: Buffer, db?: CartographyDB): string;
+/**
+ * Recursive, structure-preserving walker — same shape as `redactValue`
+ * (`src/tools.ts`): strings → {@link pseudonymizeString}, arrays → map,
+ * objects → per-value recurse, primitives → unchanged. Object keys are left
+ * verbatim (they are schema, not data), so topology shape is invariant.
+ */
+declare function pseudonymize(value: unknown, orgKey: Buffer, db?: CartographyDB): unknown;
+/**
+ * Admin reversal: decrypt the original plaintext behind a pseudonym token, or
+ * `undefined` when the token is unknown or the ciphertext fails GCM authentication
+ * (tampered or produced under a different / rotated org key).
+ */
+declare function reversePseudonym(token: string, orgKey: Buffer, db: CartographyDB): string | undefined;
+
+/**
+ * Sharing classifier + pre-send preview (2.10).
+ *
+ * Resolves the effective sharing level for each node (a PERSONAL-host hard floor
+ * over the persisted policy), applies that level (`none` drops, `anonymized`
+ * pseudonymizes, `full` keeps raw), and builds {@link previewShare} — the exact,
+ * topology-shape-preserving payload that *would* leave the machine. This is the
+ * privacy gate 2.11/2.12 build on; nothing here performs any network I/O.
+ */
+
+/**
+ * Resolve the policy-level for a node id: the most-specific matching override
+ * wins (fewest wildcards, then longest pattern); ties and no-match fall through
+ * to `defaultLevel`. The `'*'`/`'**'` rows are the global default and always lose
+ * to any narrower match. Pure and deterministic.
+ */
+declare function resolveSharingLevel(nodeId: string, policy: SharingPolicy): SharingLevel;
+/**
+ * The effective level for a node: a PERSONAL-host hard floor (single-sourced from
+ * the bookmarks never-share list) forces `'none'` regardless of policy; otherwise
+ * the policy's resolved level for the node id applies.
+ */
+declare function resolveEffectiveLevel(node: DiscoveryNode, policy: SharingPolicy): SharingLevel;
+/**
+ * Apply a sharing level to one node:
+ * - `none`       → `null` (the node is dropped, never leaves).
+ * - `anonymized` → a clone with `id`/`name` pseudonymized and `metadata` walked
+ *                  (structure-preserving); identifying fragments tokenized.
+ * - `full`       → a structural clone, verbatim.
+ *
+ * The same deterministic `pseudonymizeString` is applied to the id here and by
+ * {@link previewShare} when remapping edges, so endpoints always resolve.
+ */
+declare function applySharingLevel(node: DiscoveryNode, level: SharingLevel, orgKey: Buffer, db?: CartographyDB): DiscoveryNode | null;
+interface SharePreviewEntry {
+    /** The original (un-anonymized) node, for the operator's side-by-side disclosure. */
+    node: DiscoveryNode;
+    level: SharingLevel;
+    /** What would actually leave: the transformed node, or `null` when dropped. */
+    payload: DiscoveryNode | null;
+}
+interface SharePreview {
+    nodes: SharePreviewEntry[];
+    /** Edges that would leave, with endpoints remapped to surviving (transformed) ids. */
+    edges: {
+        sourceId: string;
+        targetId: string;
+        relationship: string;
+    }[];
+    /** Original ids of nodes dropped at level `none`. */
+    droppedNodeIds: string[];
+}
+/**
+ * Build the exact payload that would leave for a session: resolve each node's
+ * effective level, apply it, and remap edge endpoints through the same id
+ * transform. An edge survives only when both endpoints survive — so when no node
+ * is dropped the node count, edge count, and relationship multiset are identical
+ * before/after; when some are dropped the result is a well-defined subgraph.
+ *
+ * `opts.persistReversal` (default false) controls whether anonymized fragments are
+ * written to the reversal map — pure preview need not persist; an actual
+ * pre-send transform should, so an admin can later invert.
+ */
+declare function previewShare(db: CartographyDB, sessionId: string, orgKey: Buffer, policy: SharingPolicy, opts?: {
+    persistReversal?: boolean;
+}): SharePreview;
+/**
+ * The seam 2.11 will use to suppress `ask_user` re-prompts: true when the node id
+ * is already covered by the persisted policy — either a matching override or a
+ * non-`none` default — so a matched item is never re-prompted.
+ */
+declare function isRemembered(policy: SharingPolicy, nodeId: string): boolean;
 
 /**
  * Cross-platform utilities for Linux, macOS, and Windows.
  * Centralizes all OS-specific logic so scanning tools work everywhere.
  */
 type Platform = 'linux' | 'darwin' | 'win32';
+/** OS hostname, with a stable fallback so attribution is never empty. */
+declare function hostname(): string;
+/** Current OS username, falling back to USER/USERNAME env, then a sentinel. */
+declare function osUser(): string;
+/**
+ * Stable, privacy-respecting per-install identifier: a random UUID v4 cached at
+ * `~/.cartography/machine-id` (mode 0600). No hardware fingerprinting, no command
+ * execution — allowlist-safe. If the file cannot be read or written (read-only
+ * home, missing HOME in CI), it degrades to a process-stable ephemeral UUID with a
+ * warning (optional-deps-degrade house style) rather than throwing. The id never
+ * leaves the machine in 2.9; it is opaque and non-identifying.
+ */
+declare function machineId(): string;
 declare function safeEnv(): NodeJS.ProcessEnv;
 
+/**
+ * Remove orphaned temp files from previous bookmark/history scans.
+ * Call at startup to prevent /tmp accumulation after crashes.
+ */
+declare function cleanupTempFiles(): number;
+interface BookmarkHost {
+    hostname: string;
+    port: number;
+    protocol: 'http' | 'https';
+    source: string;
+}
+
 /**
  * Scanner plugin contract.
  *
@@ -389,6 +1879,19 @@ interface ScanContext {
         timeout?: number;
         env?: NodeJS.ProcessEnv;
     }) => string;
+    /**
+     * Injectable seam: resolve a command to its path ('' if absent). Defaults to the
+     * real `commandExists` when omitted. Lets scanners run deterministically in tests.
+     */
+    commandExists?: (cmd: string) => string;
+    /** Injectable seam: raw listening-port output. Defaults to `scanListeningPorts`. */
+    scanListeningPorts?: () => string;
+    /** Injectable seam: raw established-connection output (3.2). Defaults to `scanEstablishedConnections`. */
+    scanEstablishedConnections?: () => string;
+    /** Injectable seam: cross-platform file search (3.2). Defaults to `findFiles`. */
+    findFiles?: (dirs: string[], patterns: string[], maxDepth: number, limit: number) => string;
+    /** Injectable seam: browser-bookmark host source. Defaults to `scanAllBookmarks`. */
+    scanBookmarks?: () => Promise<BookmarkHost[]>;
 }
 interface ScanResult {
     /** Deterministically classified nodes. */
@@ -416,23 +1919,597 @@ interface Scanner {
 declare class ScannerRegistry {
     private scanners;
     register(scanner: Scanner): this;
+    /**
+     * Register a {@link Scanner} produced by an external plugin package. Validates
+     * the shape (throws `ZodError` on mismatch), namespaces the id to
+     * `plugin:<pkg>:<id>` (avoiding collisions with built-ins and across plugins),
+     * wraps `scan()` so the scanner's `ctx.run` is gated by its declared
+     * `allowedCommands` intersected with the central read-only allowlist
+     * ({@link checkReadOnly}), and freezes the wrapper. Reuses the duplicate-id
+     * guard in {@link register}.
+     *
+     * The gated runner delegates the actual execution to the host-supplied
+     * `ctx.run` (the platform runner), so the global read-only floor still applies
+     * and `allowedCommands` is a *second*, scanner-scoped least-privilege boundary.
+     * A command runs only if its leading executable is declared AND the whole
+     * command passes `checkReadOnly`; otherwise the runner returns `''` (the
+     * documented "blocked → ''" contract).
+     */
+    registerExternal(pkg: string, scanner: Scanner): this;
     get(id: string): Scanner | undefined;
     list(): Scanner[];
     /** Scanners whose `platforms` include the given platform. */
     forPlatform(platform: Platform): Scanner[];
 }
 
+/**
+ * Hostname substrings that indicate a personal site — never catalogued, and the
+ * hard floor for the 2.10 sharing policy (a personal host is forced to `'none'`
+ * regardless of policy). Single-sourced here and shared via {@link isPersonalHost}
+ * so the never-share list never forks.
+ */
+declare const PERSONAL: string[];
+/** True when `host` matches a PERSONAL substring (case-insensitive). */
+declare function isPersonalHost(host: string): boolean;
 declare const bookmarksScanner: Scanner;
 
+/**
+ * The Cartography MCP server — the package's primary, LLM-agnostic interface.
+ *
+ * It exposes the discovered infrastructure topology as Model Context Protocol
+ * **Resources** (read-only context, progressive disclosure), a small set of query
+ * **Tools** (parameterized lookups), and reusable **Prompts**. Any MCP host —
+ * Claude Code, Cursor, Cline, Windsurf, the Vercel AI SDK, LangGraph — can drive
+ * it; the package never needs to know which model is in use.
+ */
+
+/** A pluggable search backend; defaults to lexical search, can be upgraded to semantic. */
+type SearchFn = (db: CartographyDB, sessionId: string, query: string, opts: {
+    types?: readonly string[];
+    limit: number;
+}) => Promise<Array<{
+    node: NodeRow;
+    score?: number;
+}>>;
+/** A pluggable discovery backend invoked by the `run_discovery` tool. */
+type DiscoveryFn = (db: CartographyDB, sessionId: string, opts: {
+    hint?: string;
+    mode?: 'replace' | 'update';
+}) => Promise<{
+    nodes: number;
+    edges: number;
+    delta?: TopologyDelta;
+}>;
+interface CreateMcpServerOptions {
+    /** Database instance. If omitted, one is opened at `config.dbPath`. */
+    db?: CartographyDB;
+    /** Path to the SQLite catalog (used when `db` is not provided). */
+    dbPath?: string;
+    /** Session to serve: a session id, or `'latest'` (default) for the newest discovery. */
+    session?: string | 'latest';
+    /**
+     * Tenant/organization whose topology this server serves. Defaults to DEFAULT_TENANT
+     * (`'local'`). Session resolution is scoped to this tenant, so a server bound to one
+     * tenant never surfaces another tenant's sessions/nodes/edges. This is a data-scoping
+     * partition, not an authorization boundary (RBAC is Phase 4).
+     */
+    tenant?: string;
+    /** Semantic/lexical search backend. Defaults to lexical `searchNodes`. */
+    search?: SearchFn;
+    /** Discovery backend for `run_discovery`/`refresh`. Optional. */
+    discovery?: DiscoveryFn;
+    /**
+     * Central-collector org (2.12). When set, `get_summary` returns the org-wide,
+     * cross-machine merged summary (`db.getOrgSummary(org)`) instead of the single-
+     * session view. Used by server-mode; unset preserves the local single-session
+     * behaviour exactly. The org is normalized to a tenant.
+     */
+    org?: string;
+}
+/**
+ * Build a fully-configured Cartography MCP server. Call `.connect(transport)` to run it.
+ */
+declare function createMcpServer(opts?: CreateMcpServerOptions): McpServer;
+
+/**
+ * Transport bindings for the Cartography MCP server.
+ *
+ * - **stdio**: the local-first default — zero network, every client supports it.
+ * - **Streamable HTTP**: a single `/mcp` endpoint for team/remote use, bound to
+ *   localhost with DNS-rebinding protection. The deprecated SSE transport is not used.
+ */
+
+/** Connect a server over stdio (resolves when the transport closes). */
+declare function runStdio(server: McpServer): Promise<void>;
+interface HttpOptions {
+    port?: number;
+    host?: string;
+    /** Extra allowed Host headers (defaults to localhost:port variants). */
+    allowedHosts?: string[];
+    /** Allowed Origin headers (defaults to none → same-origin only). */
+    allowedOrigins?: string[];
+    /**
+     * Shared secret required in the `Authorization: Bearer <token>` header.
+     * Mandatory when binding a non-loopback host; optional (and enforced when
+     * present) on loopback.
+     */
+    token?: string;
+    /**
+     * Central-collector ingest hook (2.12). When set, an authenticated `POST /ingest`
+     * **write** route is exposed: it inherits the *same* bearer auth and non-loopback
+     * host-allowlist guards as `/mcp` (the route adds no separate hardening path), size-
+     * caps the body, parses JSON, and returns the hook's `{ status, body }`. When unset,
+     * `/ingest` 404s exactly like any other path — the collector stays dark by default.
+     */
+    onIngest?: (body: unknown) => {
+        status: number;
+        body: unknown;
+    };
+}
+/**
+ * Start a Streamable HTTP server. A fresh MCP server instance is created per
+ * session via `factory`, so multiple clients can connect concurrently.
+ */
+declare function runHttp(factory: () => McpServer, opts?: HttpOptions): Promise<http.Server>;
+
+/**
+ * Shared HTTP auth + bind-hardening primitives.
+ *
+ * Extracted verbatim from `src/mcp/transports.ts` so the MCP transport, the REST/
+ * GraphQL API server (4.2), and any future HTTP surface consume **one** provably-
+ * identical implementation of the CVE-2025-66414 guards, the constant-time bearer
+ * compare, and the default Host allowlist. The allowlist — not any one caller — is
+ * the security boundary; centralizing it here keeps every networked surface on the
+ * same posture and makes the behavior unit-testable in isolation.
+ */
+/** Loopback hosts are safe to bind without an explicit Host allowlist. */
+declare const LOOPBACK_HOSTS: ReadonlySet<string>;
+/** True when `host` is a loopback address (safe to bind without an allowlist/token). */
+declare function isLoopbackHost(host: string): boolean;
+/** Constant-time comparison to avoid leaking the token via timing. */
+declare function timingSafeEqual(a: string, b: string): boolean;
+/**
+ * Extract the bearer token from an Authorization header, if present. Parsed with
+ * linear string ops (no regex) so a user-controlled header can never trigger
+ * polynomial backtracking (ReDoS) — `^Bearer\s+(.+)$` is ambiguous between `\s+`
+ * and `.+` on a long run of spaces.
+ */
+declare function bearerToken(header: string | undefined): string | undefined;
+/**
+ * Returns true if the request is authenticated: a request is authenticated when no
+ * token is configured (open loopback dev mode) OR the `Authorization: Bearer` value
+ * is present and constant-time-equal to the configured token. The caller maps a
+ * `false` to a 401.
+ */
+declare function checkBearer(authorizationHeader: string | undefined, token: string | undefined): boolean;
+interface BindGuardOptions {
+    host: string;
+    port: number;
+    allowedHosts?: string[];
+    token?: string;
+}
+/**
+ * Enforce the CVE-2025-66414 + mandatory-token guards before binding. Throws the
+ * exact errors `runHttp` raised inline, so existing transport behavior is preserved:
+ * a non-loopback bind requires BOTH an explicit `allowedHosts` allowlist AND a token.
+ */
+declare function assertSafeBind(opts: BindGuardOptions): void;
+/** Default Host allowlist: the bound host plus the localhost variants, all `:port`. */
+declare function defaultAllowedHosts(host: string, port: number): string[];
+
+/**
+ * Per-request tenant resolution for the API server (4.2).
+ *
+ * The tenant (org-scope) is a first-class request property: it is resolved once,
+ * up front, and threaded into every {@link QueryBackend} call so isolation is
+ * structural, not bolted on. A request may name a tenant via the
+ * `X-Cartograph-Tenant` header or a `?tenant=` query param; absent either, it
+ * defaults to the server's configured default (normally `DEFAULT_TENANT='local'`).
+ *
+ * Validation reuses `normalizeTenant` (the single charset-allowlisted validator,
+ * `^[\w.@:+-]{1,128}$`) — but here we **reject** a malformed value with a typed
+ * error (→ HTTP 400) rather than silently falling back, so a client never believes
+ * it is scoped to one tenant while being served another. The raw input is never
+ * reflected into a response.
+ */
+
+declare const TENANT_HEADER = "x-cartograph-tenant";
+/** The supplied tenant value did not pass the charset/length allowlist → HTTP 400. */
+declare class InvalidTenantError extends Error {
+    constructor();
+}
+interface TenantOptions {
+    /** Default tenant when the request names none. Defaults to `DEFAULT_TENANT` ('local'). */
+    defaultTenant?: string;
+    /** Header to read the tenant from. Defaults to `x-cartograph-tenant`. */
+    header?: string;
+}
+/**
+ * Resolve the tenant from the request header or `?tenant=` query param, else the
+ * configured default. A supplied-but-malformed value throws {@link InvalidTenantError}
+ * (the caller maps it to a 400) instead of silently defaulting.
+ */
+declare function resolveTenant(req: IncomingMessage, url: URL, opts?: TenantOptions): TenantContext;
+
+/**
+ * The read-only API HTTP server (4.2), on Node's built-in `http` (zero new runtime dep).
+ *
+ * Request flow mirrors the MCP transport (`src/mcp/transports.ts`): the CVE-2025-66414
+ * bind guards run at startup (shared `assertSafeBind`); per request the Host header is
+ * checked against the allowlist (DNS-rebinding), then the bearer token is verified
+ * **before any backend access**, then the tenant is resolved, then the route dispatches.
+ * REST handlers are pure (`rest.ts`); GraphQL is wired when enabled (`graphql.ts`). One
+ * structured stderr access line per request — never the token, never query values.
+ */
+
+interface ApiServerOptions extends BindGuardOptions {
+    backend: QueryBackend;
+    version: string;
+    /** CORS Origin allowlist. Default: none (same-origin only). */
+    allowedOrigins?: string[];
+    /** Tenant resolution options (header name / default tenant). */
+    tenant?: TenantOptions;
+    /** Expose `/graphql` (default true). */
+    graphql?: boolean;
+    /** Access logger (stderr). */
+    log?: (msg: string) => void;
+}
+/** Start the read-only API server. Resolves once it is listening. */
+declare function runApi(opts: ApiServerOptions): Promise<http.Server>;
+
+/**
+ * OpenAPI 3.1 document generation for the read-only API (4.2).
+ *
+ * The document is **generated from the zod response schemas** (`schemas.ts`), never
+ * hand-maintained, so it cannot drift from what the server actually returns. A
+ * committed copy lives at `docs/api/openapi.json`; a test asserts the built document
+ * deep-equals it (drift guard) and validates under `ajv`.
+ *
+ * `zodToJsonSchema` is a small, fail-closed projection covering exactly the zod
+ * constructs `schemas.ts` uses (object/array/string/number/integer/boolean/enum/
+ * literal/record/optional). An unsupported construct throws, so a future schema
+ * change can't be silently mis-projected. (The provider tool layer has its own flat
+ * converter in `src/providers/zod-schema.ts`; this one is recursive and serves the
+ * API's nested response shapes.)
+ */
+
+/** Project a zod schema to a JSON-Schema (2020-12) fragment. Fail-closed on the unknown. */
+declare function zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown>;
+interface OpenApiOptions {
+    version: string;
+}
+/** Build the OpenAPI 3.1 document from the zod schemas + the static route table. Deterministic. */
+declare function buildOpenApiDocument(opts: OpenApiOptions): Record<string, unknown>;
+
+/**
+ * Hand-rolled, zero-dependency GraphQL layer for the read-only API (4.2).
+ *
+ * Mirrors REST over `POST /graphql` (and serves the SDL on `GET /graphql`) without
+ * adding a `graphql`/`apollo` runtime dependency. Resolvers delegate to the same
+ * {@link QueryBackend} and reuse the REST projections (`rest.ts`), so REST and GraphQL
+ * return byte-identical shapes and the consent posture stays in one place. It is
+ * strictly **read-only**: there is no `Mutation` type and a `mutation` document is
+ * rejected. A small tokenizer/parser handles the query subset the schema needs
+ * (fields, arguments, variables, nested selections) and a minimal `__schema`
+ * introspection response keeps GraphiQL-style clients working.
+ */
+
+interface GraphqlDeps {
+    backend: QueryBackend;
+}
+interface GraphqlResult {
+    data?: unknown;
+    errors?: Array<{
+        message: string;
+    }>;
+}
+declare const SDL = "# Cartograph read-only GraphQL API (4.2). Mirrors the REST surface.\nschema { query: Query }\n\ntype Query {\n  summary(session: String): Summary\n  nodes(search: String, types: [String!], limit: Int, offset: Int, session: String): NodeConnection\n  node(id: String!, session: String): Node\n  dependencies(id: String!, direction: Direction, maxDepth: Int, session: String): Dependencies\n  diff(base: String!, current: String!): Diff\n  sessions: [Session!]!\n}\n\nenum Direction { downstream upstream both }\n\ntype Totals { nodes: Int! edges: Int! }\ntype Count { key: String! value: Int! }\ntype TopConnected { id: String! name: String! type: String! degree: Int! }\ntype Anomaly { nodeId: String! kind: String! severity: String! reason: String! }\ntype Cost { amount: Float! currency: String! period: String! source: String }\ntype CostRollup { key: String! currency: String! period: String! total: Float! nodes: Int! }\ntype CostCoverage { withCost: Int! total: Int! }\n\ntype Node {\n  id: String! type: String! name: String! confidence: Float!\n  domain: String subDomain: String qualityScore: Float owner: String cost: Cost tags: [String!]!\n}\ntype DependencyNode {\n  id: String! type: String! name: String! confidence: Float!\n  domain: String subDomain: String qualityScore: Float owner: String cost: Cost tags: [String!]! depth: Int!\n}\ntype Edge { sourceId: String! targetId: String! relationship: String! confidence: Float! evidence: String! }\n\ntype Summary {\n  sessionId: String!\n  totals: Totals!\n  topConnected: [TopConnected!]!\n  anomalies: [Anomaly!]!\n  contributors: Int!\n  costByDomain: [CostRollup!]!\n  costByOwner: [CostRollup!]!\n  costCoverage: CostCoverage!\n}\n\ntype NodeConnection { nodes: [Node!]! total: Int! limit: Int! offset: Int! }\ntype Dependencies { root: Node direction: Direction! maxDepth: Int! nodes: [DependencyNode!]! edges: [Edge!]! }\n\ntype SessionEndpoint { sessionId: String! startedAt: String! nodeCount: Int! edgeCount: Int! }\ntype DiffSummary { nodesAdded: Int! nodesRemoved: Int! nodesChanged: Int! edgesAdded: Int! edgesRemoved: Int! }\ntype NodeChange { id: String! changedFields: [String!]! confidenceDelta: Float! }\ntype DiffNodes { added: [Node!]! removed: [Node!]! changed: [NodeChange!]! unchanged: Int! }\ntype DiffEdges { added: [Edge!]! removed: [Edge!]! unchanged: Int! }\ntype DiffAnomalies { added: [Anomaly!]! }\ntype Diff {\n  base: SessionEndpoint! current: SessionEndpoint! summary: DiffSummary!\n  nodes: DiffNodes! edges: DiffEdges! anomalies: DiffAnomalies!\n}\n\ntype Session { id: String! mode: String! startedAt: String! completedAt: String name: String tenant: String! lastScannedAt: String }\n";
+/** Execute a `{ query, variables, operationName }` request. Read-only; rejects mutations. */
+declare function executeGraphql(ctx: TenantContext, body: unknown, deps: GraphqlDeps): Promise<GraphqlResult>;
+/** `GET /graphql` → the SDL as text/plain. */
+declare function handleGraphqlGet(): {
+    status: number;
+    body: string;
+};
+
+/**
+ * Shared entry logic for the read-only API server (4.2), used by both the dedicated
+ * `cartography-api` binary and the `api` CLI sub-command. Mirrors `src/mcp/start.ts`:
+ * opens the catalog, builds the SQLite query backend, resolves the bearer token from
+ * `--token`/`CARTOGRAPHY_HTTP_TOKEN`, and starts `runApi`. All logging is to stderr;
+ * the token value is never logged (only whether one is set).
+ */
+
+interface StartApiOptions {
+    dbPath?: string;
+    session?: string | 'latest';
+    port?: number;
+    host?: string;
+    allowedHosts?: string[];
+    allowedOrigins?: string[];
+    token?: string;
+    /** Expose `/graphql` (default true). */
+    graphql?: boolean;
+    /** Default tenant served when a request names none. */
+    tenant?: string;
+    log?: (msg: string) => void;
+}
+interface ParsedApiArgs extends StartApiOptions {
+    /** `--help`/`-h` was passed; the caller should print usage and exit 0. */
+    help?: boolean;
+}
+/** Parse `cartography-api` argv into StartApiOptions (unit-testable, no side effects). */
+declare function parseApiArgs(argv: string[]): ParsedApiArgs;
+/** Open the catalog, build the read backend, and start the API server. Returns the server. */
+declare function startApi(opts?: StartApiOptions): Promise<Server>;
+
 declare const installedAppsScanner: Scanner;
 
+/** Well-known listening ports → node type + service name. */
+declare const PORT_MAP: Record<number, {
+    type: NodeType;
+    service: string;
+}>;
 /** Extract distinct listening port numbers from ss/lsof/PowerShell output. */
 declare function extractListeningPorts(raw: string): number[];
 declare const portsScanner: Scanner;
 
+/**
+ * AWS infrastructure scanner.
+ *
+ * Read-only AWS CLI discovery (`describe`/`list` actions, JSON output) mapped to
+ * deterministic nodes. Detection is a cheap `commandExists('aws')` check, so an
+ * absent CLI skips the scanner without throwing. Every command stays within the
+ * read-only allowlist's `aws` gate and uses `--output json` for stable parsing.
+ */
+
+declare const cloudAwsScanner: Scanner;
+
+/**
+ * Google Cloud Platform scanner.
+ *
+ * Read-only `gcloud … list` discovery with `--format=json` for stable parsing,
+ * mapped to deterministic nodes. Detection is `commandExists('gcloud')`; an
+ * absent CLI skips the scanner. Every command stays within the read-only
+ * allowlist's `gcloud` gate.
+ */
+
+declare const cloudGcpScanner: Scanner;
+
+/**
+ * Azure infrastructure scanner.
+ *
+ * Read-only `az … list/show` discovery with `--output json` for stable parsing,
+ * mapped to deterministic nodes. Detection is `commandExists('az')`; an absent
+ * CLI skips the scanner. Subscription / resource-group scoping comes from the
+ * hint. Every command stays within the read-only allowlist's `az` gate.
+ */
+
+declare const cloudAzureScanner: Scanner;
+
+/**
+ * Kubernetes scanner.
+ *
+ * Read-only `kubectl get … -o json` discovery mapped to deterministic nodes and
+ * edges. Detection is `commandExists('kubectl')`; an absent CLI skips the
+ * scanner. The cluster node anchors `contains` edges to its hosts and pods, and
+ * a `connects_to` edge is emitted from a service to a running pod when the pod's
+ * labels match the service's selector — only when both endpoints are in the
+ * result set (the driver prunes dangling edges anyway). Pod enumeration is
+ * bounded to keep `run_discovery` latency predictable on large clusters.
+ */
+
+declare const k8sScanner: Scanner;
+
+/**
+ * Local database scanner.
+ *
+ * Probes locally-installed DB clients (read-only) and discovers SQLite files in
+ * app-data directories, mapping reachable servers to deterministic nodes. Each
+ * client is only probed when present (`commandExists`), so an absent CLI never
+ * throws and never produces a node. The expensive home-directory / config-file
+ * find is opt-in via the `deep` hint token, keeping the default deterministic
+ * `run_discovery` path fast. Connection strings are credential-redacted before
+ * persistence.
+ */
+
+declare const databasesScanner: Scanner;
+
+/**
+ * Established-connections scanner (3.2).
+ *
+ * Reads the host's live TCP connections (read-only) and infers `connects_to`
+ * edges from a single local `host:localhost` node to any recognized listening
+ * service (`${type}:localhost:${port}` from {@link PORT_MAP}). The server-side
+ * node is only kept when `portsScanner` also mapped that port in the same run —
+ * the in-batch endpoint gate in `runLocalDiscovery` drops edges to ports nothing
+ * is listening on (graceful degradation, never an error).
+ */
+
+interface EstablishedConn {
+    localPort: number;
+    remoteHost: string;
+    remotePort: number;
+}
+/**
+ * Parse established connections from `ss -tnp`, `lsof -nP`, or PowerShell output
+ * (pure, host-independent). Deduplicates and silently ignores unparseable rows.
+ *
+ * Recognized shapes:
+ *  - ss:    `ESTAB 0 0 127.0.0.1:54321 127.0.0.1:5432 …`
+ *  - lsof:  `node 1 u … TCP 127.0.0.1:54321->127.0.0.1:5432 (ESTABLISHED)`
+ *  - PS:    `127.0.0.1:54321 -> 127.0.0.1:5432`
+ */
+declare function parseEstablished(raw: string): EstablishedConn[];
+declare const connectionsScanner: Scanner;
+
+/**
+ * Service & reverse-proxy config scanner (3.2).
+ *
+ * Infers *declared* dependency edges from local config without running any service:
+ *  - connection-string env vars (`DATABASE_URL`, `REDIS_URL`, …) → `reads_from` /
+ *    `depends_on` to `${type}:localhost:${port}`, confidence `connection-string` (0.6);
+ *  - nginx `upstream` / `proxy_pass` host:port → `depends_on`, confidence `config-declared` (0.7);
+ *  - docker-compose `depends_on:` → `container:<svc> depends_on container:<dep>`, 0.7.
+ *
+ * **Security boundary:** connection strings routinely embed credentials and
+ * `sanitizeUntrusted` (applied later in `insertEdge`) is NOT a credential filter, so
+ * this scanner redacts userinfo / `password=` *before* the value reaches `evidence`.
+ */
+
+/**
+ * Replace credentials in a connection string with `****` (the security boundary).
+ * Strips the `user:pass@` userinfo and any `password=`/`pwd=` query token.
+ */
+declare function redactConnectionString(url: string): string;
+/**
+ * Parse nginx `upstream { server host:port; }` and `proxy_pass http://host:port`
+ * directives into `{ host, port }` targets (pure, host-independent).
+ */
+declare function parseNginxUpstreams(raw: string): {
+    host: string;
+    port: number;
+}[];
+/**
+ * Parse docker-compose `depends_on:` blocks (both list and map form) into a
+ * `{ service, dependsOn[] }` array (pure). Indentation-based, dependency-free.
+ */
+declare function parseComposeDeps(raw: string): {
+    service: string;
+    dependsOn: string[];
+}[];
+/**
+ * Map a connection-string env var to a candidate edge (pure). Returns the
+ * relationship, the target service port, and a **credential-redacted** evidence
+ * string — or null when the scheme/port is not recognized.
+ */
+declare function parseConnectionString(name: string, url: string): {
+    relationship: EdgeRelationship;
+    service: string;
+    port: number;
+    evidence: string;
+} | null;
+declare const serviceConfigScanner: Scanner;
+
+/**
+ * Confidence rubric for inferred dependency edges (3.2).
+ *
+ * A single source of truth so every scanner that infers an edge draws its
+ * `confidence` from the same strictly-ordered tier set, and downstream consumers
+ * (compliance 3.4, anomaly 3.6) can rank evidence quality consistently. All values
+ * are in `(0,1]`; confidence is never fabricated — an absent evidence source yields
+ * no edge rather than a low-confidence guess.
+ */
+/** Evidence tiers for inferred dependency edges, strongest first. */
+type EvidenceKind = 'established-connection' | 'config-declared' | 'connection-string' | 'co-location';
+/** Single source of truth for edge confidence. Strictly ordered, all in (0,1]. */
+declare const CONFIDENCE: Record<EvidenceKind, number>;
+/** Build a self-describing, auditable evidence string with an ISO-8601 UTC stamp. */
+declare function evidenceLine(kind: EvidenceKind, detail: string): string;
+
+/**
+ * Shared helpers for the cloud / k8s / database scanners.
+ *
+ * These keep the provider scanners (`cloud-aws`, `cloud-gcp`, `cloud-azure`,
+ * `k8s`, `databases`) small and consistent: JSON parsing that never throws,
+ * provider-parameter extraction from the single `ScanContext.hint` channel
+ * (validated against the same strict patterns the agent tools use), and the
+ * `=== KEY ===` report formatter so the structured + raw-report output shape
+ * stays identical to the legacy agent-tool reports.
+ */
+/**
+ * Parse JSON CLI output. Returns `undefined` for empty output, our sentinel
+ * placeholders (`(error or not available)`, `(skipped …)`), or malformed JSON —
+ * it never throws, so a scanner degrades to "no nodes" instead of crashing the
+ * discovery run.
+ */
+declare function safeJson<T = unknown>(raw: string): T | undefined;
+/** Provider parameters parsed out of a {@link ScanContext.hint}. */
+interface ScanHintParams {
+    namespace?: string;
+    region?: string;
+    profile?: string;
+    project?: string;
+    subscription?: string;
+    resourceGroup?: string;
+    /** Leftover non-`key=value` terms (back-compat with the installed-apps hint use). */
+    free: string;
+}
+/**
+ * Parse `key=value` provider parameters from a `ScanContext.hint`, validating
+ * each value against its strict pattern via {@link assertSafeScanArg} (throws on
+ * an injection payload — even a read-only one the allowlist would otherwise
+ * permit). Unknown tokens flow through to {@link ScanHintParams.free} unchanged.
+ */
+declare function parseScanHint(hint: string | undefined): ScanHintParams;
+/** Render `=== KEY ===\n…` report sections (the legacy agent-tool report shape). */
+declare function buildReport(sections: Array<[string, string]>): string;
+
+/** The only surface a plugin's `register()` touches. */
+interface ScannerPluginApi {
+    /** Register a scanner the host will namespace, command-gate, and freeze. */
+    registerScanner(scanner: Scanner): void;
+}
+/** The default-exported shape a `@datasynx/scanner-*` package implements. */
+interface ScannerPlugin {
+    /** Human-readable plugin name (informational; the package name is the identity). */
+    name: string;
+    /** Register the plugin's scanners through the host-provided API. */
+    register(api: ScannerPluginApi): void;
+}
+/**
+ * Identity helper a plugin author default-exports. It only narrows the type so
+ * editors guide authoring; it adds no runtime behaviour.
+ */
+declare function definePlugin(plugin: ScannerPlugin): ScannerPlugin;
+/**
+ * Zod shape validating a {@link Scanner} produced by an external plugin.
+ * `platforms` uses the concrete `Platform` literals so an invalid platform is
+ * rejected at registration; `detect`/`scan` are validated as callables only
+ * (their async signatures cannot be expressed in zod) — behavioural safety comes
+ * from the gated `ctx.run` wrapper plus the per-scanner runtime try/catch.
+ */
+declare const ScannerShape: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    platforms: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodEnum<{
+        linux: "linux";
+        darwin: "darwin";
+        win32: "win32";
+    }>>]>;
+    allowedCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    detect: z.ZodCustom<(ctx: ScanContext) => boolean | Promise<boolean>, (ctx: ScanContext) => boolean | Promise<boolean>>;
+    scan: z.ZodCustom<(ctx: ScanContext) => Promise<ScanResult>, (ctx: ScanContext) => Promise<ScanResult>>;
+}, z.core.$strip>;
+/**
+ * Validate an unknown value as a {@link Scanner}; throws `ZodError` on mismatch.
+ * Returns the original value (the parsed result discards the live function
+ * references), so the caller keeps the real `detect`/`scan` closures.
+ */
+declare function validateScanner(value: unknown): Scanner;
+
 /** A registry pre-loaded with the built-in deterministic scanners. */
 declare function defaultRegistry(): ScannerRegistry;
 
+/**
+ * Opt-in scanner-plugin loader.
+ *
+ * Resolves the explicitly configured plugin package names (consent-first: no
+ * filesystem auto-scan), dynamically `import()`s each in its own try/catch, and
+ * registers its scanners through {@link ScannerRegistry.registerExternal}
+ * (validated, namespaced, command-gated, frozen). One bad plugin — a
+ * non-resolvable name, a missing/invalid default export, a `register()` that
+ * throws, or a malformed scanner that fails zod validation — is logged via
+ * `logWarn` and skipped. It never aborts discovery (optional-deps degrade
+ * pattern, mirroring `src/semantic/search.ts`).
+ */
+
+/**
+ * Load each configured plugin package into the given registry. Returns the
+ * package names that loaded and registered successfully (for audit/reporting).
+ */
+declare function loadPlugins(registry: ScannerRegistry, pkgs: readonly string[]): Promise<string[]>;
+
 /**
  * Deterministic, LLM-free local discovery.
  *
@@ -446,18 +2523,48 @@ declare function defaultRegistry(): ScannerRegistry;
 interface LocalDiscoveryOptions {
     hint?: string;
     registry?: ScannerRegistry;
+    /**
+     * Opt-in scanner plugin package names to load (consent-first). Honoured only
+     * when no explicit `registry` is supplied — an injected registry is used
+     * verbatim, so tests and advanced callers stay in full control.
+     */
+    plugins?: string[];
     /** Called after each scanner with a short progress line. */
     onProgress?: (line: string) => void;
+    /**
+     * Override individual {@link ScanContext} fields. Production omits this and the
+     * real platform helpers are used; tests inject deterministic sources
+     * (`commandExists`, `scanListeningPorts`, `scanBookmarks`) so the built-in
+     * scanners run against known inputs without depending on the host.
+     */
+    ctx?: Partial<ScanContext>;
+    /**
+     * `'replace'` (default) preserves today's append-all behavior: every scanned
+     * node/edge is upserted/inserted into the session. `'update'` (2.1 incremental
+     * discovery) reads the session's prior state, diffs it against the current scan,
+     * and applies only the delta — upserting changed/added, pruning removed (nodes
+     * and edges), and stamping `last_scanned_at`. Same `session_id` either way.
+     */
+    mode?: 'replace' | 'update';
 }
-declare function runLocalDiscovery(db: CartographyDB, sessionId: string, opts?: LocalDiscoveryOptions): Promise<{
+interface LocalDiscoveryResult {
     nodes: number;
     edges: number;
     scanners: string[];
-}>;
-/** Adapter matching the MCP `DiscoveryFn` signature. */
-declare function localDiscoveryFn(registry?: ScannerRegistry): (db: CartographyDB, sessionId: string, opts: {
+    /** Present only in `'update'` mode: the delta applied to the session (2.1). */
+    delta?: TopologyDelta;
+}
+declare function runLocalDiscovery(db: CartographyDB, sessionId: string, opts?: LocalDiscoveryOptions): Promise<LocalDiscoveryResult>;
+/**
+ * Adapter matching the MCP `DiscoveryFn` signature. When no explicit `registry`
+ * is provided, the opt-in `plugins` list is loaded onto the default registry on
+ * each discovery run (so late-installed plugins are picked up).
+ */
+declare function localDiscoveryFn(registry?: ScannerRegistry, plugins?: string[]): (db: CartographyDB, sessionId: string, opts: {
     hint?: string;
+    mode?: "replace" | "update";
 }) => Promise<{
+    delta?: TopologyDelta | undefined;
     nodes: number;
     edges: number;
 }>;
@@ -520,12 +2627,175 @@ declare class VectorStore {
  * or return nothing.
  */
 
+/** Options for {@link createSemanticSearch}. */
+interface SemanticSearchOptions {
+    /** Logger for mode/degradation diagnostics (stderr). No-op if omitted. */
+    log?: (msg: string) => void;
+}
 /**
  * Build a {@link SearchFn} that prefers semantic (vector) search and falls back to
  * lexical. Pass an explicit embedder, or let it lazily load the local transformer
- * (returns a lexical-only function if none is available).
+ * (returns a lexical-only function if none is available). Pass `opts.log` to record
+ * which mode was resolved — semantic readiness or the reason it degraded to lexical.
+ */
+declare function createSemanticSearch(db: CartographyDB, embedder?: EmbeddingProvider, opts?: SemanticSearchOptions): Promise<SearchFn>;
+
+/**
+ * Types for the `install` harness — the layer that writes Cartography's MCP
+ * server entry into each host's native config file (JSON / TOML / YAML).
+ *
+ * A {@link ClientSpec} is a declarative description of one host: where its config
+ * lives per OS and scope, what serialization format it uses, and how to splice a
+ * server entry into that host's particular schema (`mcpServers`, `servers`,
+ * `context_servers`, `[mcp_servers]`, `extensions`, …). The merge engine and CLI
+ * are generic; all host-specific knowledge lives in specs.
+ */
+type ConfigFormat = 'json' | 'toml' | 'yaml';
+type Scope = 'global' | 'project';
+type OsKind = 'mac' | 'win' | 'linux';
+/** A transport-agnostic description of the Cartography MCP server to register. */
+interface ServerEntry {
+    /** stdio command (mutually exclusive with `url`). */
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /** Streamable HTTP endpoint (mutually exclusive with `command`). */
+    url?: string;
+}
+/** Everything a spec needs to resolve a config path; injectable for tests. */
+interface ResolveContext {
+    scope: Scope;
+    os: OsKind;
+    /** User home directory. */
+    home: string;
+    /** Project/working directory (for project-scoped configs). */
+    cwd: string;
+    /** Environment variables (for `%APPDATA%` etc. on Windows). */
+    env: Record<string, string | undefined>;
+}
+interface ClientSpec {
+    /** Stable id used on the CLI, e.g. `claude-code`. */
+    id: string;
+    /** Human label, e.g. `Claude Code`. */
+    label: string;
+    format: ConfigFormat;
+    /** Resolve the absolute config path for the given scope/OS, or undefined if unsupported. */
+    path(ctx: ResolveContext): string | undefined;
+    /** Pure: return a new config object with `entry` spliced in under `serverName`. */
+    apply(existing: Record<string, unknown>, serverName: string, entry: ServerEntry): Record<string, unknown>;
+    /** Optional caveat surfaced to the user (e.g. "uses `servers`, not `mcpServers`"). */
+    note?: string;
+}
+
+/**
+ * Format-agnostic (de)serialization for host config files. JSON keeps 2-space
+ * indentation; TOML uses smol-toml; YAML uses the `yaml` package. Empty or
+ * whitespace-only input parses to an empty object so a fresh install starts clean.
+ */
+
+declare function parseConfig(text: string, format: ConfigFormat): Record<string, unknown>;
+declare function serializeConfig(obj: Record<string, unknown>, format: ConfigFormat): string;
+
+/**
+ * Idempotent deep-merge of plain objects. Used by client specs to splice a server
+ * entry into an existing config without clobbering unrelated keys. Arrays and
+ * scalars from `source` replace those in `target`; nested plain objects merge
+ * recursively. `source` is never mutated; `target` is cloned.
+ */
+declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<string, unknown>): T;
+
+/**
+ * Shared entry-shape helpers. Most hosts accept the Claude-Desktop-style object
+ * (`command`/`args`/`env` for stdio, `url`/`type` for HTTP); specs that diverge
+ * (VS Code `type`, Zed `source`, Codex TOML, …) compose or override these.
+ */
+
+/** The common `{ command, args, env }` | `{ type:'http', url }` server object. */
+declare function mcpServerObject(entry: ServerEntry): Record<string, unknown>;
+
+/**
+ * The canonical Cartography MCP server entry every client spec receives. Kept in
+ * one place so the npx invocation (and any future packaging change) is defined
+ * exactly once and reused across all hosts.
+ */
+
+declare const PACKAGE_NAME = "@datasynx/agentic-ai-cartography";
+declare const MCP_BIN = "cartography-mcp";
+declare const DEFAULT_SERVER_NAME = "cartography";
+interface EntryOptions {
+    /** `http` produces a `url` entry; otherwise stdio via npx. */
+    transport?: 'stdio' | 'http';
+    /** HTTP endpoint (used when transport === 'http'). */
+    url?: string;
+    /** Extra environment variables to inject. */
+    env?: Record<string, string>;
+    /** Extra package arguments appended after the bin name (e.g. `--db`, `--session`). */
+    packageArgs?: string[];
+}
+/** Build the default server entry (stdio via `npx` unless an HTTP url is given). */
+declare function defaultServerEntry(opts?: EntryOptions): ServerEntry;
+
+/**
+ * Generic install planning/applying. `planInstall` is pure relative to a provided
+ * context (reads the existing file, computes the merged result, never writes) so
+ * it powers both `--dry-run` and the real write in `applyInstall`.
+ */
+
+interface InstallPlan {
+    client: string;
+    label: string;
+    path: string;
+    format: ConfigFormat;
+    /** Existing file contents ('' when the file does not exist). */
+    before: string;
+    /** Contents that would be written. */
+    after: string;
+    fileExists: boolean;
+    changed: boolean;
+    note?: string;
+}
+/** Detect the current OS kind. */
+declare function currentOs(): OsKind;
+/** Build a real resolve context from the running environment. */
+declare function defaultContext(scope: Scope): ResolveContext;
+interface PlanOptions {
+    serverName?: string;
+    entry: ServerEntry;
+}
+/** Compute what installing `entry` into `spec` would change. Reads the config file but never writes. */
+declare function planInstall(spec: ClientSpec, ctx: ResolveContext, opts: PlanOptions): InstallPlan;
+/** Write a plan's result to disk, creating parent directories as needed. */
+declare function applyInstall(plan: InstallPlan): void;
+/** A minimal line-oriented diff for `--dry-run` output. */
+declare function renderDiff(before: string, after: string): string;
+
+/**
+ * Registry of supported MCP hosts. The merge engine and CLI are generic; every
+ * host-specific detail (config path, format, schema key) lives in a `ClientSpec`
+ * here. New hosts are added by appending a spec — no engine changes required.
  */
-declare function createSemanticSearch(db: CartographyDB, embedder?: EmbeddingProvider): Promise<SearchFn>;
+
+/** All registered clients, in display order. Extended by later milestones. */
+declare const CLIENTS: ClientSpec[];
+declare function getClient(id: string): ClientSpec | undefined;
+declare function listClients(): ReadonlyArray<Pick<ClientSpec, 'id' | 'label' | 'format' | 'note'>>;
+
+/**
+ * One-click install deeplinks for hosts that support them. Cursor expects a
+ * **Base64**-encoded server config; VS Code expects **URL-encoded** JSON — mixing
+ * the two encodings is a classic mistake, so each has its own helper.
+ */
+
+/** `cursor://…/mcp/install?name=<name>&config=<base64 JSON of the server config>`. */
+declare function cursorDeeplink(name: string, entry: ServerEntry): string;
+interface VscodeDeeplinkOptions {
+    /** Target VS Code Insiders (`vscode-insiders://`). */
+    insiders?: boolean;
+}
+/** `vscode://mcp/install?<URL-encoded JSON>` where the JSON is `{ name, ...serverConfig }`. */
+declare function vscodeDeeplink(name: string, entry: ServerEntry, opts?: VscodeDeeplinkOptions): string;
+/** A `code --add-mcp '<json>'` CLI one-liner (alternative to the deeplink). */
+declare function codeAddMcpCommand(name: string, entry: ServerEntry): string;
 
 /**
  * Circuit breaker for sequential CLI scans.
@@ -542,8 +2812,66 @@ declare function createScanRunner(runFn: (cmd: string, opts?: {
 interface CartographyToolsOptions {
     /** Called when the agent needs a human answer. Return the user's response. */
     onAskUser?: (question: string, context?: string) => Promise<string>;
+    /** Max characters of a single tool response (sanitized + truncated). Default 100 000. */
+    maxResponseBytes?: number;
 }
+/**
+ * Sanitize untrusted scan output (strip invisible/control characters) and cap it
+ * at `max` characters so a single verbose scan can never blow the agent's context
+ * window. Appends an explicit truncation notice when clamped.
+ */
+declare function clampText(raw: string, max: number): string;
 declare function stripSensitive(target: string): string;
+/**
+ * Strict patterns for the cloud/k8s scan parameters that get spliced into a
+ * shell command. `run()` re-checks the final command against the read-only
+ * allowlist, but values are validated here first so an injection payload never
+ * reaches the shell — not even a read-only one (e.g. `; cat ~/.ssh/id_rsa`)
+ * that the allowlist would otherwise permit and which could disclose files.
+ */
+declare const SCAN_ARG_PATTERNS: {
+    readonly 'k8s-namespace': RegExp;
+    readonly 'aws-region': RegExp;
+    readonly 'aws-profile': RegExp;
+    readonly 'gcp-project': RegExp;
+    readonly 'azure-subscription': RegExp;
+    readonly 'azure-resource-group': RegExp;
+};
+type ScanArgKind = keyof typeof SCAN_ARG_PATTERNS;
+/** Throw if `value` fails the strict pattern for `kind`; otherwise return it. */
+declare function assertSafeScanArg(kind: ScanArgKind, value: string): string;
+/** Redact `user:password@` credentials embedded in any URL/DSN-like string. */
+declare function redactSecrets(value: string): string;
+/** Recursively redact secrets from arbitrary metadata before persistence. */
+declare function redactValue(value: unknown): unknown;
+/** The MCP text-content shape every tool handler returns. */
+interface ToolResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+}
+/**
+ * Provider-neutral tool definition: a zod input shape plus a handler that returns
+ * the MCP text-content shape. This is the single source of truth for the discovery
+ * tools — the Claude provider wraps these via the SDK `tool()` factory, while
+ * OpenAI/Ollama convert `inputShape` to JSON Schema and call `handler` directly.
+ */
+interface AgentTool {
+    name: string;
+    description: string;
+    /** Raw zod shape (ZodRawShape) for the tool input. */
+    inputShape: z.ZodRawShape;
+    /** Host-side gating hints (never a security boundary). */
+    annotations: Record<string, boolean>;
+    handler: (args: Record<string, unknown>) => Promise<ToolResult>;
+}
+/**
+ * Build the discovery tool handlers with **no** SDK dependency. Returns the same
+ * handler bodies used by the Claude path, exposed neutrally so any provider can
+ * reuse them. `buildCartographyToolDefinitions` wraps these for the Claude SDK.
+ */
+declare function buildCartographyToolHandlers(db: CartographyDB, sessionId: string, opts?: CartographyToolsOptions): Promise<AgentTool[]>;
 declare function createCartographyTools(db: CartographyDB, sessionId: string, opts?: CartographyToolsOptions): Promise<McpServerConfig>;
 
 declare const safetyHook: HookCallback;
@@ -602,16 +2930,667 @@ type DiscoveryEvent = {
 type AskUserFn = (question: string, context?: string) => Promise<string>;
 declare function runDiscovery(config: CartographyConfig, db: CartographyDB, sessionId: string, onEvent?: (event: DiscoveryEvent) => void, onAskUser?: AskUserFn, hint?: string): Promise<void>;
 
+/** Inputs a provider needs to run one discovery session. */
+interface AgentRunContext {
+    config: CartographyConfig;
+    db: CartographyDB;
+    sessionId: string;
+    systemPrompt: string;
+    initialPrompt: string;
+    onAskUser?: AskUserFn;
+    /** Wall-clock deadline (epoch ms). Providers MUST stop and emit `done` past this. */
+    deadlineMs: number;
+}
+/**
+ * A provider-neutral agent backend. Yields the existing `DiscoveryEvent` stream.
+ * Implementations MUST: enforce `config.maxTurns`, honor `ctx.deadlineMs`, route
+ * every shell command through `checkReadOnly` + `run()`, and write an audit row per
+ * executed tool so the audit trail is identical across providers.
+ */
+interface AgentProvider {
+    readonly name: ProviderName;
+    /** Throw a clear Error if the optional dep / API key / CLI is missing. */
+    ensureAvailable(config: CartographyConfig): Promise<void>;
+    run(ctx: AgentRunContext): AsyncIterable<DiscoveryEvent>;
+}
+type ProviderFactory = () => AgentProvider;
+/** Registry of provider factories; the single source of truth for valid provider names. */
+declare class ProviderRegistry {
+    private readonly factories;
+    register(name: ProviderName, factory: ProviderFactory): void;
+    has(name: string): name is ProviderName;
+    resolve(name: ProviderName): AgentProvider;
+    names(): ProviderName[];
+}
+
+declare function createDefaultRegistry(): ProviderRegistry;
+declare const defaultProviderRegistry: ProviderRegistry;
+
+declare function createClaudeProvider(): AgentProvider;
+
+declare function createOpenAIProvider(): AgentProvider;
+
+declare function createOllamaProvider(): AgentProvider;
+
+interface JsonSchema {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required: string[];
+    additionalProperties: boolean;
+}
+/** Convert a flat ZodRawShape used by the discovery tools to a JSON Schema object. */
+declare function shapeToJsonSchema(shape: z.ZodRawShape): JsonSchema;
+
+declare function createBashTool(): AgentTool;
+
+/**
+ * Drift classification + dispatch (3.1).
+ *
+ * Layered on top of the pure topology delta (`diffTopology` → `db.diffSessions`):
+ * `classifyDrift` turns a `TopologyDiff` into a severity-ranked `DriftAlert`
+ * (deterministic, DB-agnostic, exhaustively unit-testable), and `runDrift` is the
+ * one-shot runner — the seam scheduled discovery (2.5) calls after a scan — that
+ * resolves the latest two sessions, classifies, threshold-filters, fans out to the
+ * configured sinks (one sink's failure never aborts the others), and writes an
+ * audit event. No new tables, no migration; read-only except the audit row.
+ */
+
+/** Return the highest severity among items; `info` for an empty list. */
+declare function maxSeverity(items: DriftAlertItem[]): Severity$1;
+/**
+ * Names of the metadata keys whose value changed and which warrant escalation to
+ * `critical`. Empty unless the node-changed touched `metadata` and a
+ * security-relevant key (case-insensitive) actually differs before→after.
+ */
+declare function securityRelevantChange(change: NodeChange): string[];
+/**
+ * Classify a topology diff into a severity-tagged alert. Pure & deterministic
+ * (only `generatedAt` depends on `now`). Rules:
+ *  - node-removed, edge-removed                  → warning  (lost capability / connectivity)
+ *  - node-changed touching a security metadata   → critical
+ *    key
+ *  - node-changed (other fields)                 → info
+ *  - node-added, edge-added                      → info
+ * Overall severity = maxSeverity(items).
+ */
+declare function classifyDrift(diff: TopologyDiff, now?: Date): DriftAlert;
+/** Drop items strictly below `min`; recompute the overall severity over what's kept. */
+declare function filterBySeverity(alert: DriftAlert, min: Severity$1): DriftAlert;
+interface RunDriftOptions {
+    base?: string;
+    current?: string;
+    minSeverity?: Severity$1;
+}
+/**
+ * Resolve base/current (newest-first `getSessions`, like the CLI/MCP surfaces),
+ * classify, filter below `minSeverity`, dispatch to all configured sinks
+ * (`Promise.allSettled` — one sink failure never aborts the others), and record an
+ * audit event. Returns the alert, or `null` when fewer than two sessions exist
+ * (graceful no-op). The seam scheduled discovery (2.5) calls post-scan.
+ */
+declare function runDrift(db: CartographyDB, config: CartographyConfig, opts?: RunDriftOptions): Promise<DriftAlert | null>;
+
+/**
+ * Anomaly detection (3.6) — pure, deterministic flagging of standing structural risk.
+ *
+ * Knows nothing about the database; operates on plain `NodeRow[]` + an in-memory
+ * degree map so it can be unit-tested in isolation and reused by the CLI, the MCP
+ * server, and the scheduled-scan alert path (3.1). Same topology always yields the
+ * same anomalies with identical `reason` strings (mirrors `deriveSessionName`). No
+ * LLM, no I/O, no dependency. `reason` interpolates only the structured `nodeId` and
+ * numeric scores — never raw node name/metadata (prompt-injection safe).
+ */
+
+/** Flag zero/weak-degree nodes. degree 0 → high; 1..orphanWeakDegree → low. */
+declare function detectOrphans(nodes: NodeRow[], degree: ReadonlyMap<string, number>, thresholds?: AnomalyThresholds): Anomaly[];
+/** Flag unmanaged-type or undomained low-confidence/quality nodes. */
+declare function detectShadowIt(nodes: NodeRow[], thresholds?: AnomalyThresholds): Anomaly[];
+/** Aggregate + stable sort (nodeId, then kind). Returns [] for an empty topology. */
+declare function detectAnomalies(nodes: NodeRow[], degree: ReadonlyMap<string, number>, thresholds?: AnomalyThresholds): Anomaly[];
+/** Anomalies present in `current` but absent in `base`, keyed by (nodeId, kind). Pure & order-stable. */
+declare function newAnomalies(base: Anomaly[], current: Anomaly[]): Anomaly[];
+
+/**
+ * Natural-language topology query resolver (3.5) — deterministic, LLM-free.
+ *
+ * Turns a plain-English question ("services that depend on the payments DB") into a
+ * structured intent, then composes the existing primitives — the injected `SearchFn`
+ * (semantic↔lexical degradation inherited for free) + `db.getDependencies` + a
+ * post-traversal type filter — and echoes the parsed intent for explainability.
+ * No LLM, no new exec path, read-only. The NL string is sanitized + length-clamped
+ * (ReDoS-safe: only linear, anchored patterns).
+ */
+
+/** The relationship the operator asked about, in resolver-native terms. */
+type NlRelation = 'depends-on' | 'depended-on-by' | 'connected-to' | 'list';
+/** Maps a parsed relation to the `db.getDependencies` direction. Single source of truth. */
+declare const RELATION_TO_DIRECTION: {
+    readonly 'depends-on': "downstream";
+    readonly 'depended-on-by': "upstream";
+    readonly 'connected-to': "both";
+    readonly list: undefined;
+};
+/** Structured intent parsed from a natural-language question. */
+interface NlIntent {
+    readonly query: string;
+    readonly subjectQuery: string;
+    readonly relation: NlRelation;
+    readonly direction?: 'downstream' | 'upstream' | 'both';
+    /** Concrete node types the *result* set is restricted to (post-traversal), if any. */
+    readonly typeFilter?: readonly NodeType[];
+    /** True when no relation pattern matched and we degraded to a search-only list. */
+    readonly degraded: boolean;
+}
+interface NlQueryResult {
+    readonly intent: NlIntent;
+    readonly anchors: Array<{
+        node: NodeRow;
+        score?: number;
+    }>;
+    readonly nodes: Array<NodeRow & {
+        depth?: number;
+    }>;
+    readonly paths: EdgeRow[];
+}
+interface NlQueryOptions {
+    readonly maxDepth?: number;
+    readonly anchorLimit?: number;
+}
+/** Parse a natural-language question into a structured {@link NlIntent}. Pure & deterministic. */
+declare function parseNlQuery(raw: string): NlIntent;
+/** Execute a parsed intent: anchor via `search`, traverse, then filter results by type. */
+declare function executeNlQuery(db: CartographyDB, sessionId: string, search: SearchFn, intent: NlIntent, opts?: NlQueryOptions): Promise<NlQueryResult>;
+/** Convenience: parse + execute in one call. */
+declare function resolveNlQuery(db: CartographyDB, sessionId: string, search: SearchFn, raw: string, opts?: NlQueryOptions): Promise<NlQueryResult>;
+
+/**
+ * Cost attribution (3.3) — turn the topology into a FinOps lens.
+ *
+ * A pluggable `CostSource` yields `{ owner, cost }` keyed by node id; `enrichCosts`
+ * applies it to a session via targeted, idempotent UPDATEs (never `INSERT OR
+ * REPLACE`, so other node fields are untouched). The first source is `CsvCostSource`
+ * — deterministic, provider-agnostic, no new dependency. Live billing-API sources
+ * (AWS Cost Explorer, GCP/Azure) are future implementations of the same interface.
+ */
+
+/** One attribution line keyed to a node. `cost`/`owner` may be partially present. */
+interface CostRecord {
+    nodeId: string;
+    owner?: string;
+    cost?: CostEntry;
+}
+/** A pluggable provider of cost/owner attribution, keyed by node id. */
+interface CostSource {
+    readonly id: string;
+    /** Attribution keyed by node id. An absent/unauthorized source resolves to an empty map (degrade). */
+    fetch(): Promise<Map<string, CostRecord>>;
+}
+interface EnrichResult {
+    source: string;
+    total: number;
+    matched: number;
+    unmatched: number;
+    unmatchedIds: string[];
+}
+/** How a CSV row is resolved to a node id when no explicit `nodeId` column is given. */
+type MatchStrategy = 'nodeId' | 'name' | 'tag';
+interface CsvCostSourceOptions {
+    filePath: string;
+    match?: MatchStrategy;
+    db?: CartographyDB;
+    sessionId?: string;
+}
+/**
+ * Parse a cost CSV (`nodeId,owner,amount,currency,period[,source]`, header required)
+ * into validated `CostRecord[]`. Each row's cost fields are validated via
+ * `CostEntrySchema`; a malformed row is skipped with a `logWarn` (counts only, no
+ * owner PII) — the batch never aborts.
+ */
+declare function parseCostCsv(text: string): CostRecord[];
+/** CSV-backed cost source. Resolves row→node ids per the chosen `MatchStrategy`. */
+declare class CsvCostSource implements CostSource {
+    private readonly opts;
+    readonly id: string;
+    constructor(opts: CsvCostSourceOptions);
+    fetch(): Promise<Map<string, CostRecord>>;
+}
+/**
+ * Idempotent post-pass: apply a source's attribution to a session via targeted
+ * UPDATEs. Re-running with the same source yields the same DB state. Unmatched
+ * rows (no such node id) are reported, never written.
+ */
+declare function enrichCosts(db: CartographyDB, sessionId: string, source: CostSource): Promise<EnrichResult>;
+
 declare function generateTopologyMermaid(nodes: NodeRow[], edges: EdgeRow[]): string;
 declare function generateDependencyMermaid(nodes: NodeRow[], edges: EdgeRow[]): string;
+/**
+ * Render a topology diff as a Mermaid graph: added nodes/edges in green, removed
+ * in red, changed in amber. Endpoints of added/removed edges that are otherwise
+ * unchanged are drawn as neutral "context" nodes so every edge has both ends.
+ */
+declare function generateDiffMermaid(diff: TopologyDiff): string;
 declare function exportBackstageYAML(nodes: NodeRow[], edges: EdgeRow[], org?: string): string;
 declare function exportJSON(db: CartographyDB, sessionId: string): string;
 declare function exportDiscoveryApp(nodes: NodeRow[], edges: EdgeRow[], options?: {
     theme?: 'light' | 'dark';
 }): string;
 declare function exportJGF(nodes: NodeRow[], edges: EdgeRow[]): string;
+/**
+ * Cost rolled up by domain and owner as CSV — the FinOps export. One block per
+ * scope; rows are bucketed by `(currency, period)` so mixed currencies are never
+ * summed into one figure.
+ */
+declare function exportCostCSV(summary: GraphSummary): string;
+/** The same cost rollup as JSON for programmatic consumers. */
+declare function exportCostSummary(summary: GraphSummary): string;
+/**
+ * Render a `ComplianceReport` as `json`, `markdown`, or `mermaid`. The Mermaid form
+ * reuses the diff exporter's severity-coloured `classDef` pattern: one node per gap
+ * coloured by severity, with a `"✓ No compliance gaps"` empty state.
+ */
+declare function exportComplianceReport(report: ComplianceReport, format: 'json' | 'markdown' | 'mermaid'): string;
 declare function exportAll(db: CartographyDB, sessionId: string, outputDir: string, formats?: string[]): void;
 
+/**
+ * Compliance scoring engine (3.4) — pure, deterministic, DB-free.
+ *
+ * `scoreTopology({nodes, edges}, ruleset)` mirrors `diffTopology`'s shape: plain
+ * arrays in, a structured `ComplianceReport` out. The engine is the only trusted
+ * evaluator of the declarative `RuleCheck` DSL — no `eval`, no ruleset-supplied
+ * code or regex. Iteration order is stabilised (nodes + rules sorted by id) so the
+ * report is byte-stable for a fixed `now`.
+ */
+
+interface ComplianceInput {
+    nodes: NodeRow[];
+    edges: EdgeRow[];
+}
+declare function evaluateCheck(node: NodeRow, check: RuleCheck): boolean;
+declare function evaluateRule(input: ComplianceInput, rule: ComplianceRule): ControlResult;
+/**
+ * Score a topology against a ruleset. `score = round(100 × Σweight(passed applicable) /
+ * Σweight(applicable))`, weighted by severity, with not-applicable controls excluded
+ * from the denominator. `score = null` / `status = 'not_applicable'` when nothing applies.
+ */
+declare function scoreTopology(input: ComplianceInput, ruleset: Ruleset, opts?: {
+    now?: string;
+}): ComplianceReport;
+/** Validate raw ruleset data (used by the registry and any future import path). */
+declare function loadRuleset(raw: unknown): Ruleset;
+
+/**
+ * Bundled ruleset registry (3.4). All rulesets are plain data, validated at load.
+ */
+
+/** Resolve a bundled ruleset by name, or `undefined` (callers degrade, never throw). */
+declare function getRuleset(name: string): Ruleset | undefined;
+/** List the bundled rulesets (name/version/framework/rule count) for help + degrade messages. */
+declare function listRulesets(): Array<{
+    name: string;
+    version: string;
+    framework: string;
+    ruleCount: number;
+}>;
+
+/**
+ * Plain-text compliance report formatter (3.4). Colour-free so it lives outside
+ * `cli.ts` (which owns the colour helpers and is excluded from coverage).
+ */
+
+/** Render a `ComplianceReport` as a plain-text summary with `✓`/`✗` markers. */
+declare function formatComplianceText(report: ComplianceReport): string;
+
+/**
+ * A destination for a classified drift alert. Implementations are the *only*
+ * outbound surface of the drift feature; they must degrade gracefully and must
+ * not throw for transient failures — log and resolve so the runner can continue
+ * dispatching to the remaining sinks.
+ */
+interface DriftSink {
+    /** Stable identifier for logging/audit (e.g. 'stdout', 'webhook'). */
+    readonly name: string;
+    /** Dispatch one alert. Never throws for transient failures. */
+    emit(alert: DriftAlert): Promise<void>;
+}
+
+/**
+ * Default sink: writes one severity-tagged, credential-redacted JSON line to
+ * **stdout** (the data channel) and a one-line diagnostic to **stderr**, keeping
+ * the stdout/stderr discipline the rest of the CLI follows. Fully local — no
+ * network egress.
+ */
+declare class StdoutSink implements DriftSink {
+    readonly name = "stdout";
+    emit(alert: DriftAlert): Promise<void>;
+}
+
+interface WebhookSinkOptions {
+    url: string;
+    token?: string;
+    timeoutMs?: number;
+}
+/**
+ * Outbound sink: POSTs the alert as JSON to an operator-configured endpoint. The
+ * first and only outbound network surface of the drift feature — off by default
+ * (constructed only when a `webhook` sink is explicitly configured). Hardened:
+ *  - the body is **always** `redactValue(alert)`, so no `user:password@` secret
+ *    leaves the process;
+ *  - only `stripSensitive(url)` (host:port) is ever logged — never the full URL,
+ *    the bearer token, or the body;
+ *  - the target must be `https:` (SSRF / plaintext-exfil guard) — a plaintext
+ *    `http:` URL is refused unless the host is loopback or the documented
+ *    `CARTOGRAPHY_ALLOW_INSECURE_SYNC=1` escape hatch is set (mirrors `pushDeltas`);
+ *  - degrades to a logged no-op when `fetch` is unavailable or the URL is empty;
+ *  - never throws (the runner owns retry/abort policy).
+ */
+declare class WebhookSink implements DriftSink {
+    private readonly opts;
+    readonly name = "webhook";
+    constructor(opts: WebhookSinkOptions);
+    emit(alert: DriftAlert): Promise<void>;
+}
+
+/**
+ * Construct sinks from config. Absent/empty config → `[new StdoutSink()]` (the
+ * local default). A webhook sink's token falls back to `CARTOGRAPHY_DRIFT_TOKEN`
+ * when not given explicitly (mirroring `CARTOGRAPHY_HTTP_TOKEN`). A webhook entry
+ * without a url is skipped defensively (the schema already rejects it).
+ */
+declare function buildSinks(drift?: DriftConfig): DriftSink[];
+
+/** Raised when a config file cannot be read, parsed, or validated. */
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Read and validate a JSON config file at `path`, returning a fully-resolved
+ * {@link CartographyConfig}. Merges the file's `schedule`/`entryPoints`/`dbPath`/
+ * `organization` into `defaultConfig` so every existing config invariant (e.g.
+ * `agentModel === models.lead`) is preserved.
+ *
+ * Precedence for the shared `entryPoints`/`dbPath`: a value inside the `schedule`
+ * block wins over the same file-level key (the schedule block is the more specific
+ * intent for a scheduled run).
+ *
+ * @throws {ConfigError} when the file is missing/unreadable, the JSON is malformed,
+ *   or the content fails schema validation (including unknown keys via `.strict()`).
+ */
+declare function loadConfig(path: string): CartographyConfig;
+/**
+ * Lower-level reader: parse + validate a config file into its typed shape without
+ * resolving it against `defaultConfig`. Useful for callers (e.g. WS 2.11) that need
+ * the raw file shape rather than a merged runtime config.
+ *
+ * @throws {ConfigError} on missing file, malformed JSON, or schema-validation failure.
+ */
+declare function readConfigFile(path: string): ConfigFile;
+
+/**
+ * Scheduled discovery (2.5).
+ *
+ * A thin, dependency-free cron driver over the existing read-only discovery and
+ * drift machinery. Two pure pieces — {@link parseCron} and {@link nextRun} — own
+ * a minimal 5-field cron grammar (UTC, no NPM dependency); {@link runOnce} runs a
+ * single deterministic local scan and returns the topology drift relative to the
+ * prior run. `runOnce` never invokes the Claude/agent loop and needs no API key.
+ *
+ * Reuse, not reimplementation: discovery is `runLocalDiscovery` and diffing is the
+ * pure `diffTopology` engine (surfaced here via the 2.1 incremental `mode:'update'`
+ * rescan, which already returns the delta). This module adds scheduling + per-run
+ * persistence around them.
+ */
+
+/** Parsed allowed-value sets for each cron field (all UTC). */
+interface CronFields {
+    /** 0–59 */
+    minute: Set<number>;
+    /** 0–23 */
+    hour: Set<number>;
+    /** 1–31 */
+    dom: Set<number>;
+    /** 1–12 */
+    month: Set<number>;
+    /** 0–6 (Sunday = 0) */
+    dow: Set<number>;
+}
+/**
+ * Parse a 5-field cron expression (`minute hour dom month dow`, UTC) into its
+ * matching value sets. Grammar per field: star, star-slash-n, `a`, `a-b`,
+ * `a-b`-slash-n, `a`-slash-n, and comma lists of those. Day-of-week `7`
+ * normalizes to `0` (Sunday).
+ *
+ * @throws {RangeError} when the expression is not exactly 5 fields, or any field
+ *   is out of range / non-numeric / malformed.
+ */
+declare function parseCron(expr: string): CronFields;
+/**
+ * The earliest scheduled instant strictly after `after` (UTC, second/ms truncated).
+ * Deterministic and pure: same `expr` + `after` always yields the same Date.
+ *
+ * @throws {RangeError} when `expr` is invalid, or no match is found within ~4 years.
+ */
+declare function nextRun(expr: string, after: Date): Date;
+interface ScheduledRunResult {
+    /** The session this run scanned (reused in place across runs). */
+    sessionId: string;
+    /** The prior session used as the diff base, or `undefined` on the first run. */
+    baseSessionId?: string;
+    /** Topology drift this run observed. */
+    delta: TopologyDelta;
+    /** Node count after the scan. */
+    nodes: number;
+    /** Edge count after the scan. */
+    edges: number;
+    /** Ids of the scanners that ran. */
+    scanners: string[];
+}
+/**
+ * Run one deterministic local-discovery pass and return its topology drift.
+ *
+ * Reuses the most recent prior `discover` session for this config's tenant and
+ * rescans it in place via the 2.1 incremental `mode:'update'` path (same session
+ * id, prunes vanished entities, stamps `last_scanned_at`), which already returns
+ * the delta from the pure `diffTopology` engine. When no prior session exists, it
+ * creates a fresh session, replace-scans it, and reports the whole topology as
+ * `added` (diffed against an empty base).
+ *
+ * Read-only and API-key-free. Does **not** persist the drift run — the caller does
+ * (so tests can inspect the delta first). All progress goes to stderr.
+ */
+declare function runOnce(cfg: CartographyConfig, db: CartographyDB): Promise<ScheduledRunResult>;
+
+/**
+ * Share classifier (2.11) — pure, DB-agnostic.
+ *
+ * Buckets the items of a {@link SharePreview} (the 2.10 policy-transformed payload)
+ * into `share` / `withhold` / `pending` against the persisted {@link SharingPolicy}
+ * and the set of already-shared content hashes:
+ *
+ * - A node whose transformed payload is `null` (effective level `none`, incl. the
+ *   PERSONAL-host hard floor) is **withheld** — it never leaves.
+ * - A node already pushed (its `shareHash` ∈ `sharedHashes`) is dropped (no bucket).
+ * - A surviving node covered by the policy ({@link isRemembered}) is **share** — the
+ *   employee's policy is the standing consent, so it auto-approves with no re-prompt.
+ * - A surviving node *not* covered by any policy rule/default is **pending** — new /
+ *   unmatched, queued for explicit review. Nothing in this bucket ever leaves until
+ *   the employee approves it (the load-bearing privacy invariant).
+ *
+ * Edges follow their endpoints: an edge is shareable only when both endpoints
+ * survive (already guaranteed by `previewShare`, which drops dangling edges) and
+ * both endpoint nodes land in `share`. Otherwise the edge is withheld.
+ *
+ * The transform/anonymization itself is **not** reimplemented here — it is consumed
+ * from `previewShare`. This module only routes the already-transformed items.
+ */
+
+/** One classified, ready-to-queue item carrying its outgoing (transformed) payload. */
+interface ClassifiedItem {
+    contentHash: string;
+    kind: 'node' | 'edge';
+    /** Original node id (for `node` items); the remapped source id for `edge` items. */
+    nodeId?: string;
+    /** The exact transformed bytes that would leave the machine. */
+    payload: unknown;
+}
+interface ClassifyResult {
+    /** Covered by policy → auto-approve (no re-prompt). */
+    share: ClassifiedItem[];
+    /** Effective level `none` / PERSONAL floor → suppressed; never leaves. */
+    withhold: ClassifiedItem[];
+    /** New / unmatched → queued for explicit human review. */
+    pending: ClassifiedItem[];
+}
+interface ClassifyInput {
+    preview: SharePreview;
+    policy: SharingPolicy;
+    /** `content_hash` values already pushed (status `shared`) — suppress re-share. */
+    sharedHashes: ReadonlySet<string>;
+}
+/**
+ * Route a {@link SharePreview} into share / withhold / pending buckets. Pure and
+ * deterministic: same inputs always yield the same buckets. The payloads carried
+ * here are the transformed ones from the preview, so anything routed to `share` is
+ * already anonymized per policy.
+ */
+declare function classify(input: ClassifyInput): ClassifyResult;
+
+/**
+ * Stable content hashing for the central-DB share queue (2.11).
+ *
+ * The hash is computed over the *policy-transformed* payload (what `previewShare`
+ * produces — already anonymized/dropped), so two scans that yield the same outgoing
+ * bytes map to the same `pending_shares` row (idempotent enqueue) and the same
+ * server-side dedup key. It is deterministic via `stableStringify` (recursively
+ * key-sorted JSON), so key ordering never perturbs the hash.
+ *
+ * Zero new dependencies — `node:crypto` + the existing `stableStringify`.
+ */
+/** A node or edge projected to its outgoing (already-transformed) shape. */
+type ShareKind = 'node' | 'edge';
+/**
+ * sha256 (hex) over the canonical JSON of `{ kind, payload }`. `payload` is the
+ * transformed projection — for `anonymized`/`none` items it is the anonymized form,
+ * never the raw record — so the hash is stable across scans and identical to the
+ * value the central side can dedup on.
+ */
+declare function shareHash(kind: ShareKind, payload: unknown): string;
+
+/**
+ * Outbound push client (2.11) — Cartograph's first egress path.
+ *
+ * Pushes consented, policy-transformed deltas to the central ingest endpoint over
+ * bearer-auth HTTPS. It is the inverse of the inbound MCP auth in
+ * `src/mcp/transports.ts`: instead of validating a bearer token, it *sends* one.
+ *
+ * Load-bearing privacy invariant: this function only ever sends the items it is
+ * handed, which the caller (`sync push`) draws exclusively from `getApprovedShares()`
+ * (status `approved`). The hard guards below additionally make a no-config / insecure
+ * / empty send impossible. The bearer token is NEVER logged and NEVER placed in the
+ * payload; error logging routes the URL through `stripSensitive`.
+ *
+ * Network is Node 20+ global `fetch`, injectable via `fetchImpl` so tests never hit
+ * the network. Zero new dependencies.
+ */
+
+/** One item to push. `payload` is the already-policy-transformed (anonymized) projection. */
+interface PushItem {
+    contentHash: string;
+    kind: 'node' | 'edge';
+    payload: unknown;
+}
+interface PushResult {
+    /** Items the server acknowledged. */
+    sent: number;
+    /** Batches POSTed. */
+    batches: number;
+    /** Items in batches that ultimately failed (left for a later retry). */
+    failed: number;
+    /** content hashes the server acknowledged (caller flips these to `shared`). */
+    sentHashes: string[];
+}
+interface PushOptions {
+    /** Injectable fetch (tests). Defaults to Node global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Items per batch. Defaults to `config.centralDb.batchSize ?? 100`. */
+    batchSize?: number;
+    /** Max retries per batch on 5xx / network errors. Default 4. */
+    maxRetries?: number;
+    /** Per-request timeout (ms). Default 15000. */
+    timeoutMs?: number;
+    /** Preview only — never networks. */
+    dryRun?: boolean;
+    /** Log sink (stderr by default); the token never reaches it. */
+    log?: (line: string) => void;
+    /** Sleep hook (tests inject a no-op to skip real backoff). */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Wire-format version of the push envelope (the contract WS 2.12 ingests). */
+declare const PUSH_SCHEMA_VERSION: 1;
+/**
+ * Push approved deltas. Returns counts and the acknowledged content hashes.
+ *
+ * Hard guards (the no-leak guarantee):
+ *  - missing `centralDb.url`/`token` → throws (nothing sent, fetch never called).
+ *  - non-`https:` URL → throws, unless `CARTOGRAPHY_ALLOW_INSECURE_SYNC === '1'`
+ *    (test-only, documented as unsafe; never the default).
+ *  - empty `items` → returns zeros without any network call.
+ */
+declare function pushDeltas(config: CartographyConfig, items: PushItem[], opts?: PushOptions): Promise<PushResult>;
+
+/**
+ * Central-DB sync orchestration (2.11) — the post-scan enqueue glue.
+ *
+ * After a (manual or scheduled) scan, {@link runSyncClassify} resolves the
+ * employee's persisted sharing policy (2.10), builds the policy-transformed payload
+ * via `previewShare` (already anonymized/dropped — nothing raw for `anonymized`/
+ * `none`), classifies it against the already-shared set, and enqueues the result
+ * into `pending_shares`:
+ *
+ * - `share`   → enqueued `approved` with `decided_by='rule'` (the policy *is* the
+ *               standing consent; never re-prompted).
+ * - `pending` → enqueued `pending` for explicit review (nothing leaves until approved).
+ * - `withhold`→ recorded `withheld` for the audit/`sync status` suppression count.
+ *
+ * Short-circuits to a no-op when `centralDb` is unconfigured, so an install without
+ * sync configured never writes to the queue. All writes run in one transaction.
+ */
+
+interface SyncClassifyResult {
+    enqueued: number;
+    autoShared: number;
+    withheld: number;
+}
+interface SyncClassifyOptions {
+    /** Override the org-key path / namespace (tests). Defaults to `config.organization`. */
+    orgKey?: Buffer;
+}
+/**
+ * Classify a session's topology against the persisted policy and enqueue the
+ * result. Returns counts for `pending` (`enqueued`), auto-approved (`autoShared`),
+ * and suppressed (`withheld`) items. No-op (all zeros) when sync is unconfigured.
+ */
+declare function runSyncClassify(db: CartographyDB, sessionId: string, config: CartographyConfig, opts?: SyncClassifyOptions): SyncClassifyResult;
+
+/**
+ * Sanitization of untrusted text before it enters the catalog or an LLM context
+ * window. Discovery ingests text from sources outside our control — browser
+ * bookmark titles, command output, scanner reports — which can carry hidden
+ * prompt-injection payloads using invisible Unicode (zero-width spaces,
+ * bidi/format controls, soft hyphens) or stray control characters.
+ *
+ * `sanitizeUntrusted` strips those while preserving ordinary whitespace
+ * (tab/0x09, line feed/0x0A, carriage return/0x0D) and NFC-normalizes the
+ * result. It is a no-op for normal ASCII/printable text.
+ *
+ * The set of stripped code points is defined numerically (below) rather than as
+ * a regex of literal invisible characters, so the source stays pure ASCII and
+ * auditable.
+ */
+/** Strip invisible/control characters and NFC-normalize untrusted text. */
+declare function sanitizeUntrusted(text: string): string;
+/** Recursively apply `sanitizeUntrusted` to every string in an arbitrary value. */
+declare function sanitizeValue(value: unknown): unknown;
+
 /**
  * Hex Grid Engine — flat-top axial coordinate system.
  * Reference: https://www.redblobgames.com/grids/hexagons/
@@ -705,13 +3684,13 @@ declare function buildMapData(nodes: NodeRow[], edges: EdgeRow[], options?: {
     theme?: 'light' | 'dark';
 }): CartographyMapData;
 
-declare function checkPrerequisites(): void;
-
 /**
- * Remove orphaned temp files from previous bookmark/history scans.
- * Call at startup to prevent /tmp accumulation after crashes.
+ * Provider-aware preflight. Defaults to `'claude'` so existing zero-arg callers are
+ * unaffected. For non-Claude providers, checks only what each backend needs from the
+ * environment; deeper reachability (e.g. Ollama host) is deferred to the provider's
+ * `ensureAvailable`, which degrades at run with an actionable message.
  */
-declare function cleanupTempFiles(): number;
+declare function checkPrerequisites(provider?: ProviderName): void;
 
 /**
  * Structured logging for enterprise observability.
@@ -731,4 +3710,4 @@ declare function logInfo(message: string, context?: Record<string, unknown>): vo
 declare function logWarn(message: string, context?: Record<string, unknown>): void;
 declare function logError(message: string, context?: Record<string, unknown>): void;
 
-export { type CartographyConfig, CartographyDB, type CartographyMapData, type Cluster, ClusterSchema, type Connection, ConnectionSchema, type CreateMcpServerOptions, DOMAIN_COLORS, DOMAIN_PALETTE, type DataAsset, DataAssetSchema, type DiscoveryEdge, type DiscoveryEvent, type DiscoveryFn, type DiscoveryNode, EDGE_RELATIONSHIPS, type EdgeRelationship, type EdgeRow, EdgeSchema, type EmbeddingProvider, type GraphSummary, type HttpOptions, type LocalDiscoveryOptions, type LogEntry, type LogLevel, NODE_TYPES, NODE_TYPE_GROUPS, type NodeRow, NodeSchema, type NodeType, type PolicyResult, type ScanContext, type ScanResult, type Scanner, ScannerRegistry, type SearchFn, type SessionRow, type ShellKind, type TraversalResult, VectorStore, assertReadOnly, assignColors, bookmarksScanner, buildMapData, checkPrerequisites, checkReadOnly, cleanupTempFiles, computeCentroid, computeClusterBounds, createCartographyTools, createHashEmbedder, createLocalEmbedder, createMcpServer, createScanRunner, createSemanticSearch, defaultConfig, defaultRegistry, edgesToConnections, exportAll, exportBackstageYAML, exportDiscoveryApp, exportJGF, exportJSON, extractListeningPorts, generateDependencyMermaid, generateTopologyMermaid, groupByDomain, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, installedAppsScanner, isReadOnlyCommand, layoutClusters, localDiscoveryFn, log, logDebug, logError, logInfo, logWarn, nodesToAssets, pixelToHex, portsScanner, runDiscovery, runHttp, runLocalDiscovery, runStdio, safeEnv, safetyHook, setVerbose, shadeVariant, splitSegments, stripSensitive };
+export { ANOMALY_KINDS, ANOMALY_SEVERITIES, type AgentProvider, type AgentRunContext, type AgentTool, type Anomaly, type AnomalyConfig, type AnomalyKind, type AnomalySeverity, type AnomalyThresholds, type AnonViolation, type AnonymizationLevel, type ApiServerOptions, type AskUserFn, type BindGuardOptions, CLIENTS, CONFIDENCE, COST_PERIODS, type CartographyConfig, CartographyDB, type CartographyMapData, type CentralDbConfig, CentralDbConfigSchema, type ClassifiedItem, type ClassifyInput, type ClassifyResult, type ClientSpec, type Cluster, ClusterSchema, type ComplianceInput, type ComplianceReport, ComplianceReportSchema, type ComplianceRule, ComplianceRuleSchema, type Condition, ConditionSchema, ConfigError, type ConfigFile, ConfigFileSchema, type ConfigFormat, type Connection, ConnectionSchema, type Contributor, type ControlResult, ControlResultSchema, type CostEntry, CostEntrySchema, type CostPeriod, type CostRecord, type CostSource, type CreateMcpServerOptions, type CronFields, CsvCostSource, type CsvCostSourceOptions, DEFAULT_ANOMALY_THRESHOLDS, DEFAULT_FAST_MODEL, DEFAULT_LEAD_MODEL, DEFAULT_SERVER_NAME, DEFAULT_TENANT, DOMAIN_COLORS, DOMAIN_PALETTE, DRIFT_FIELDS, type DataAsset, DataAssetSchema, type DependencyQuery, type DiscoveryEdge, type DiscoveryEvent, type DiscoveryFn, type DiscoveryNode, type DriftAlert, type DriftAlertItem, type DriftConfig, DriftConfigSchema, type DriftField, type DriftItemKind, type DriftRunRow, type DriftSink, type DriftSinkConfig, EDGE_RELATIONSHIPS, type EdgeRelationship, type EdgeRow, EdgeSchema, type EmbeddingProvider, type EnrichResult, type EntryOptions, type EstablishedConn, type EvidenceKind, type FragmentKind, type GraphSummary, type HealthResult, type HttpOptions, INGEST_SCHEMA_VERSION, type IngestEnvelope, IngestEnvelopeSchema, type IngestHandler, type IngestOptions, type IngestResponse, type IngestResult, type InstallPlan, InvalidTenantError, LOOPBACK_HOSTS, type LocalDiscoveryOptions, type LocalDiscoveryResult, type LogEntry, type LogLevel, MCP_BIN, type MatchStrategy, NODE_TYPES, NODE_TYPE_GROUPS, type NlIntent, type NlQueryOptions, type NlQueryResult, type NlRelation, type NodeAttribution, type NodeChange, type NodeIdentity, type NodeQuery, type NodeRow, NodeSchema, type NodeType, type NodesResult, NotFoundError, OUTPUT_FORMATS, type OrgKeyOptions, type OrgSummary, type OsKind, type OutputFormat, PACKAGE_NAME, PENDING_STATUSES, PERSONAL, PORT_MAP, PRIVATE_IP, PUSH_SCHEMA_VERSION, type ParsedApiArgs, type PendingShareRow, type PendingStatus, type PlanOptions, type PolicyResult, type ProviderFactory, type ProviderName, ProviderRegistry, type PushItem, type PushOptions, type PushResult, type QueryBackend, RELATION_TO_DIRECTION, type ResolveContext, type RuleCheck, RuleCheckSchema, type RuleScope, type Ruleset, RulesetSchema, type RunDriftOptions, SCAN_ARG_PATTERNS, SDL, SECURITY_METADATA_KEYS, SEVERITIES, SEVERITY_WEIGHT, SHARING_LEVELS, type ScanArgKind, type ScanContext, type ScanHintParams, type ScanResult, type Scanner, type ScannerPlugin, type ScannerPluginApi, ScannerRegistry, ScannerShape, type ScheduleConfig, ScheduleConfigSchema, type ScheduledRunResult, type Scope, type SearchFn, type SemanticSearchOptions, type ServerEntry, type SessionRow, type Severity, type SharePreview, type SharePreviewEntry, type SharingLevel, SharingLevelSchema, type SharingPolicy, type ShellKind, SqliteQueryBackend, SqliteStoreBackend, type StartApiOptions, StdoutSink, type StoreBackend, type SyncClassifyOptions, type SyncClassifyResult, TENANT_HEADER, type TenantContext, type TenantOptions, type ToolResult, type TopologyDelta, type TopologyDiff, type TopologyInput, type TraversalResult, VectorStore, WebhookSink, type WebhookSinkOptions, applyInstall, applySharingLevel, assertReadOnly, assertSafeBind, assertSafeScanArg, assignColors, bearerToken, bookmarksScanner, buildCartographyToolHandlers, buildMapData, buildOpenApiDocument, buildReport, buildSinks, centralDbFromEnv, checkBearer, checkPrerequisites, checkReadOnly, clampText, classify, classifyDrift, cleanupTempFiles, cloudAwsScanner, cloudAzureScanner, cloudGcpScanner, codeAddMcpCommand, computeCentroid, computeClusterBounds, computeIdentity, connectionsScanner, contentHash, createBashTool, createCartographyTools, createClaudeProvider, createDefaultRegistry, createHashEmbedder, createIngestHandler, createLocalEmbedder, createMcpServer, createOllamaProvider, createOpenAIProvider, createScanRunner, createSemanticSearch, createSqliteQueryBackend, currentOs, cursorDeeplink, databasesScanner, deepMerge, defaultAllowedHosts, defaultConfig, defaultContext, defaultProviderRegistry, defaultRegistry, defaultServerEntry, definePlugin, deriveSessionName, detectAnomalies, detectOrphans, detectShadowIt, diffTopology, edgesToConnections, enrichCosts, evaluateCheck, evaluateRule, evidenceLine, executeGraphql, executeNlQuery, exportAll, exportBackstageYAML, exportComplianceReport, exportCostCSV, exportCostSummary, exportDiscoveryApp, exportJGF, exportJSON, extractListeningPorts, filterBySeverity, findAnonViolations, formatComplianceText, generateDependencyMermaid, generateDiffMermaid, generateTopologyMermaid, getClient, getRuleset, globalId, groupByDomain, handleGraphqlGet, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, hmacKey, hostname, ingestEnvelope, installedAppsScanner, isLoopbackHost, isPersonalHost, isReadOnlyCommand, isRemembered, k8sScanner, keyMetaOf, layoutClusters, listClients, listRulesets, loadConfig, loadOrgKey, loadPlugins, loadRuleset, localDiscoveryFn, log, logDebug, logError, logInfo, logWarn, machineId, maxSeverity, mcpServerObject, newAnomalies, nextRun, nodesToAssets, normalizeId, normalizeTenant, orgKeyPath, osUser, parseApiArgs, parseComposeDeps, parseConfig, parseConnectionString, parseCostCsv, parseCron, parseEstablished, parseNginxUpstreams, parseNlQuery, parseScanHint, pixelToHex, planInstall, portsScanner, previewShare, pseudonymize, pseudonymizeFragment, pseudonymizeString, pushDeltas, readConfigFile, redactConnectionString, redactSecrets, redactValue, renderDiff, resolveEffectiveLevel, resolveNlQuery, resolveSharingLevel, resolveTenant, revalidateAnonymized, reversalKey, reversePseudonym, rotateOrgKey, runApi, runDiscovery, runDrift, runHttp, runLocalDiscovery, runOnce, runStdio, runSyncClassify, safeEnv, safeJson, safetyHook, sanitizeUntrusted, sanitizeValue, scoreTopology, securityRelevantChange, serializeConfig, serviceConfigScanner, setVerbose, shadeVariant, shapeToJsonSchema, shareHash, splitSegments, stableStringify, startApi, stripSensitive, timingSafeEqual, validateScanner, vscodeDeeplink, zodToJsonSchema };