@datasynx/agentic-ai-cartography 2.7.0 → 2.8.0

package/dist/index.d.cts

@@ -1469,9 +1469,18 @@ interface NodeIdentity {
     /** Secondary merge key — content hash that catches `id` drift between machines. */
     contentHash: string;
 }
+/**
+ * A value that may be produced synchronously (SQLite, `better-sqlite3`) or
+ * asynchronously (a graph DB over the async Bolt driver, 4.3). The ingest core
+ * `await`s every backend call, so a sync implementation incurs no overhead and the
+ * SQLite path stays byte-for-byte synchronous.
+ */
+type Awaitable<T> = T | Promise<T>;
 /**
  * A provider-agnostic central store. All operations are scoped to a single tenant
- * (`org`); there is no cross-tenant read or write path.
+ * (`org`); there is no cross-tenant read or write path. Methods are **async-capable**
+ * (4.3): `SqliteStoreBackend` returns synchronously, `GraphStoreBackend` returns
+ * Promises; consumers await either.
  */
 interface StoreBackend {
     /**
@@ -1480,15 +1489,15 @@ interface StoreBackend {
      * `'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';
+    upsertNode(org: string, node: DiscoveryNode, identity: NodeIdentity, contributor: Contributor): Awaitable<'created' | 'merged'>;
     /** Insert an edge under `org` (idempotent on the logical `(source, target, relationship)` key). */
-    insertEdge(org: string, edge: DiscoveryEdge): void;
+    insertEdge(org: string, edge: DiscoveryEdge): Awaitable<void>;
     /** Org-wide aggregate summary (merged counts across all contributors). */
-    getSummary(org: string): OrgSummary;
+    getSummary(org: string): Awaitable<OrgSummary>;
     /** Contributors for a merged logical node (test/audit helper). */
-    getContributors(globalId: string): Contributor[];
+    getContributors(globalId: string): Awaitable<Contributor[]>;
     /** Release any underlying resources. */
-    close(): void;
+    close(): Awaitable<void>;
 }
 
 /**
@@ -1519,6 +1528,76 @@ declare class SqliteStoreBackend implements StoreBackend {
     close(): void;
 }
 
+/**
+ * `GraphStoreBackend` (4.3) — an opt-in central-store backend over a Bolt-speaking
+ * graph database (Neo4j / Memgraph). Implements the async-capable {@link StoreBackend}
+ * seam so the central collector's merge + org-summary path can scale to 10K+ nodes on a
+ * native graph engine, while SQLite stays the zero-config default.
+ *
+ * `neo4j-driver` is an OPTIONAL dependency, dynamically imported by `openStoreBackend`
+ * (`src/store/index.ts`); this module depends only on a minimal structural Bolt interface,
+ * so it compiles and the package degrades gracefully when the driver is absent. The driver
+ * is injected (constructor), which also lets tests drive it with a mock — no live DB in CI.
+ *
+ * Merge identity mirrors SQLite: a logical node is keyed by `(org, globalId)`; the
+ * `contentHash` is stored + indexed for the id-drift secondary collapse (best-effort here,
+ * tracked as a follow-up). Contributors are `(org, globalId, machineId)` with max-confidence.
+ */
+
+interface BoltRecord {
+    get(key: string): unknown;
+}
+interface BoltResult {
+    records: BoltRecord[];
+}
+interface BoltSession {
+    run(cypher: string, params?: Record<string, unknown>): Promise<BoltResult>;
+    close(): Promise<void>;
+}
+interface BoltDriver {
+    session(): BoltSession;
+    close(): Promise<void>;
+    verifyConnectivity?(): Promise<unknown>;
+}
+declare class GraphStoreBackend implements StoreBackend {
+    private readonly driver;
+    constructor(driver: BoltDriver);
+    private run;
+    upsertNode(org: string, node: DiscoveryNode, identity: NodeIdentity, contributor: Contributor): Promise<'created' | 'merged'>;
+    insertEdge(org: string, edge: DiscoveryEdge): Promise<void>;
+    getSummary(org: string): Promise<OrgSummary>;
+    getContributors(globalId: string): Promise<Contributor[]>;
+    close(): Promise<void>;
+}
+
+/**
+ * Central-store backend factory (4.3).
+ *
+ * `openStoreBackend` returns a {@link GraphStoreBackend} only when a graph backend is
+ * explicitly requested AND the optional `neo4j-driver` is installed AND the server is
+ * reachable; otherwise it logs a structured WARN and returns the always-available
+ * {@link SqliteStoreBackend}. A missing driver or an unreachable graph server therefore
+ * NEVER breaks the collector — it degrades to SQLite (the "optional deps degrade" locked
+ * constraint). SQLite stays the zero-config default.
+ */
+
+interface StoreBackendOptions {
+    /** `'graph'` opts into the graph DB; anything else (default) uses SQLite. */
+    backend?: 'sqlite' | 'graph';
+    /** Bolt URL, e.g. `bolt://graph.internal:7687` or `neo4j+s://…`. */
+    graphUrl?: string;
+    graphUser?: string;
+    graphPassword?: string;
+    /** Injected driver factory (tests). Defaults to dynamically importing `neo4j-driver`. */
+    driverFactory?: (url: string, user: string, password: string) => Promise<BoltDriver>;
+}
+/**
+ * Resolve the central store backend. Graph when requested + available; else SQLite.
+ * The returned backend is owned by the caller (call `close()` on shutdown for the graph
+ * backend; the SQLite backend's `close()` is a no-op — the `CartographyDB` is shared).
+ */
+declare function openStoreBackend(db: CartographyDB, opts?: StoreBackendOptions): Promise<StoreBackend>;
+
 /**
  * `QueryBackend` — the **read-only** query seam for the API server (4.2).
  *
@@ -1770,7 +1849,7 @@ interface IngestOptions {
  * 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;
+declare function ingestEnvelope(store: StoreBackend, envelope: IngestEnvelope, opts?: IngestOptions): Promise<IngestResult>;
 
 /**
  * Ingest backpressure for the central collector (4.7).
@@ -1825,7 +1904,7 @@ interface IngestResponse {
     /** Extra response headers (e.g. `Retry-After` on a 429). */
     headers?: Record<string, string>;
 }
-type IngestHandler = (body: unknown) => IngestResponse;
+type IngestHandler = (body: unknown) => Promise<IngestResponse>;
 interface IngestHandlerOptions extends IngestOptions {
     /** Per-org ingest rate limiter (4.7 backpressure). Over-quota → 429 + Retry-After. */
     quota?: RateLimiter;
@@ -2186,6 +2265,12 @@ interface CreateMcpServerOptions {
      * behaviour exactly. The org is normalized to a tenant.
      */
     org?: string;
+    /**
+     * Org-wide summary source (4.3). When set (server-mode with a graph backend), the
+     * org `get_summary` reads from here instead of `db.getOrgSummary` — so a graph-DB
+     * collector serves its own merged aggregate. Defaults to the SQLite central store.
+     */
+    orgSummary?: (org: string) => OrgSummary | Promise<OrgSummary>;
     /**
      * The authenticated principal (4.5 RBAC). When set, mutating tools (`run_discovery`)
      * are gated by role: a `viewer` is refused with a forbidden error. Read tools are
@@ -2229,7 +2314,11 @@ interface HttpOptions {
      * 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) => {
+    onIngest?: (body: unknown) => Promise<{
+        status: number;
+        body: unknown;
+        headers?: Record<string, string>;
+    }> | {
         status: number;
         body: unknown;
         headers?: Record<string, string>;
@@ -4186,4 +4275,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 { ACTIONS, ANOMALY_KINDS, ANOMALY_SEVERITIES, type Action, ActionSchema, 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 AuthConfig, AuthConfigSchema, AuthorizationError, type BackstageEntity, type BackstageMapOptions, 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 CredentialConfig, CredentialConfigSchema, type CredentialDb, type CredentialRecord, type CredentialStore, type CronFields, CsvCostSource, type CsvCostSourceOptions, DEFAULT_ANOMALY_THRESHOLDS, DEFAULT_FAST_MODEL, DEFAULT_INGEST_QUOTA, 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 FetchLike, type FragmentKind, type GraphSummary, type HealthResult, type HttpOptions, INGEST_SCHEMA_VERSION, type IngestEnvelope, IngestEnvelopeSchema, type IngestHandler, type IngestHandlerOptions, type IngestOptions, type IngestResponse, type IngestResult, type InstallPlan, InvalidTenantError, type JiraIssue, type JiraOptions, JiraSink, type JiraSinkOptions, 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, PAGERDUTY_ENQUEUE_URL, PENDING_STATUSES, PERSONAL, PORT_MAP, PRIVATE_IP, PUSH_SCHEMA_VERSION, type PagerDutyEvent, PagerDutySink, type PagerDutySinkOptions, type ParsedApiArgs, type PendingShareRow, type PendingStatus, type PlanOptions, type PolicyResult, type PostJsonOptions, type Principal, PrincipalSchema, type ProviderFactory, type ProviderName, ProviderRegistry, type PushItem, type PushOptions, type PushResult, type QueryBackend, type QuotaConfig, type QuotaDecision, RELATION_TO_DIRECTION, ROLES, RateLimiter, type ResolveContext, type ResolveOptions, type Role, RoleSchema, type RuleCheck, RuleCheckSchema, type RuleScope, type Ruleset, RulesetSchema, type RunDriftOptions, SCAN_ARG_PATTERNS, SCHEMA_VERSION, 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, type SlackMessage, SlackSink, SqliteCredentialStore, SqliteQueryBackend, SqliteStoreBackend, type StartApiOptions, StdoutSink, type StoreBackend, type SyncClassifyOptions, type SyncClassifyResult, TENANT_HEADER, type TenantContext, TenantMismatchError, type TenantOptions, type ToolResult, type TopologyDelta, type TopologyDiff, type TopologyInput, type TraversalResult, VectorStore, WebhookSink, type WebhookSinkOptions, applyInstall, applySharingLevel, assertReadOnly, assertSafeBind, assertSafeScanArg, assertSameTenant, assignColors, authorize, bearerToken, bookmarksScanner, buildCartographyToolHandlers, buildMapData, buildOpenApiDocument, buildReport, buildSinks, can, 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, entitiesToYaml, evaluateCheck, evaluateRule, evidenceLine, executeGraphql, executeNlQuery, exportAll, exportBackstageYAML, exportComplianceReport, exportCostCSV, exportCostSummary, exportDiscoveryApp, exportJGF, exportJSON, extractListeningPorts, filterBySeverity, findAnonViolations, formatComplianceText, formatJira, formatPagerDuty, formatSlack, generateDependencyMermaid, generateDiffMermaid, generateTopologyMermaid, getClient, getRuleset, globalId, groupByDomain, handleGraphqlGet, hashToken, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, hmacKey, hostname, ingestEnvelope, installedAppsScanner, isLoopbackHost, isPersonalHost, isReadOnlyCommand, isRemembered, isSecureWebhookUrl, 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, postJson, previewShare, pseudonymize, pseudonymizeFragment, pseudonymizeString, pushDeltas, readConfigFile, redactConnectionString, redactSecrets, redactValue, renderDiff, resolveEffectiveLevel, resolveNlQuery, resolvePrincipal, resolveSharingLevel, resolveTenant, revalidateAnonymized, reversalKey, reversePseudonym, rotateOrgKey, runApi, runDiscovery, runDrift, runHttp, runLocalDiscovery, runOnce, runStdio, runSyncClassify, safeEnv, safeJson, safetyHook, sanitizeUntrusted, sanitizeValue, scopeReads, scoreTopology, securityRelevantChange, serializeConfig, serviceConfigScanner, setVerbose, shadeVariant, shapeToJsonSchema, shareHash, splitSegments, stableStringify, startApi, stripSensitive, timingSafeEqual, toBackstageEntities, validateScanner, vscodeDeeplink, zodToJsonSchema };
+export { ACTIONS, ANOMALY_KINDS, ANOMALY_SEVERITIES, type Action, ActionSchema, 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 AuthConfig, AuthConfigSchema, AuthorizationError, type Awaitable, type BackstageEntity, type BackstageMapOptions, type BindGuardOptions, type BoltDriver, type BoltRecord, type BoltResult, type BoltSession, 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 CredentialConfig, CredentialConfigSchema, type CredentialDb, type CredentialRecord, type CredentialStore, type CronFields, CsvCostSource, type CsvCostSourceOptions, DEFAULT_ANOMALY_THRESHOLDS, DEFAULT_FAST_MODEL, DEFAULT_INGEST_QUOTA, 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 FetchLike, type FragmentKind, GraphStoreBackend, type GraphSummary, type HealthResult, type HttpOptions, INGEST_SCHEMA_VERSION, type IngestEnvelope, IngestEnvelopeSchema, type IngestHandler, type IngestHandlerOptions, type IngestOptions, type IngestResponse, type IngestResult, type InstallPlan, InvalidTenantError, type JiraIssue, type JiraOptions, JiraSink, type JiraSinkOptions, 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, PAGERDUTY_ENQUEUE_URL, PENDING_STATUSES, PERSONAL, PORT_MAP, PRIVATE_IP, PUSH_SCHEMA_VERSION, type PagerDutyEvent, PagerDutySink, type PagerDutySinkOptions, type ParsedApiArgs, type PendingShareRow, type PendingStatus, type PlanOptions, type PolicyResult, type PostJsonOptions, type Principal, PrincipalSchema, type ProviderFactory, type ProviderName, ProviderRegistry, type PushItem, type PushOptions, type PushResult, type QueryBackend, type QuotaConfig, type QuotaDecision, RELATION_TO_DIRECTION, ROLES, RateLimiter, type ResolveContext, type ResolveOptions, type Role, RoleSchema, type RuleCheck, RuleCheckSchema, type RuleScope, type Ruleset, RulesetSchema, type RunDriftOptions, SCAN_ARG_PATTERNS, SCHEMA_VERSION, 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, type SlackMessage, SlackSink, SqliteCredentialStore, SqliteQueryBackend, SqliteStoreBackend, type StartApiOptions, StdoutSink, type StoreBackend, type StoreBackendOptions, type SyncClassifyOptions, type SyncClassifyResult, TENANT_HEADER, type TenantContext, TenantMismatchError, type TenantOptions, type ToolResult, type TopologyDelta, type TopologyDiff, type TopologyInput, type TraversalResult, VectorStore, WebhookSink, type WebhookSinkOptions, applyInstall, applySharingLevel, assertReadOnly, assertSafeBind, assertSafeScanArg, assertSameTenant, assignColors, authorize, bearerToken, bookmarksScanner, buildCartographyToolHandlers, buildMapData, buildOpenApiDocument, buildReport, buildSinks, can, 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, entitiesToYaml, evaluateCheck, evaluateRule, evidenceLine, executeGraphql, executeNlQuery, exportAll, exportBackstageYAML, exportComplianceReport, exportCostCSV, exportCostSummary, exportDiscoveryApp, exportJGF, exportJSON, extractListeningPorts, filterBySeverity, findAnonViolations, formatComplianceText, formatJira, formatPagerDuty, formatSlack, generateDependencyMermaid, generateDiffMermaid, generateTopologyMermaid, getClient, getRuleset, globalId, groupByDomain, handleGraphqlGet, hashToken, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, hmacKey, hostname, ingestEnvelope, installedAppsScanner, isLoopbackHost, isPersonalHost, isReadOnlyCommand, isRemembered, isSecureWebhookUrl, k8sScanner, keyMetaOf, layoutClusters, listClients, listRulesets, loadConfig, loadOrgKey, loadPlugins, loadRuleset, localDiscoveryFn, log, logDebug, logError, logInfo, logWarn, machineId, maxSeverity, mcpServerObject, newAnomalies, nextRun, nodesToAssets, normalizeId, normalizeTenant, openStoreBackend, orgKeyPath, osUser, parseApiArgs, parseComposeDeps, parseConfig, parseConnectionString, parseCostCsv, parseCron, parseEstablished, parseNginxUpstreams, parseNlQuery, parseScanHint, pixelToHex, planInstall, portsScanner, postJson, previewShare, pseudonymize, pseudonymizeFragment, pseudonymizeString, pushDeltas, readConfigFile, redactConnectionString, redactSecrets, redactValue, renderDiff, resolveEffectiveLevel, resolveNlQuery, resolvePrincipal, resolveSharingLevel, resolveTenant, revalidateAnonymized, reversalKey, reversePseudonym, rotateOrgKey, runApi, runDiscovery, runDrift, runHttp, runLocalDiscovery, runOnce, runStdio, runSyncClassify, safeEnv, safeJson, safetyHook, sanitizeUntrusted, sanitizeValue, scopeReads, scoreTopology, securityRelevantChange, serializeConfig, serviceConfigScanner, setVerbose, shadeVariant, shapeToJsonSchema, shareHash, splitSegments, stableStringify, startApi, stripSensitive, timingSafeEqual, toBackstageEntities, validateScanner, vscodeDeeplink, zodToJsonSchema };

package/dist/index.d.ts

@@ -1469,9 +1469,18 @@ interface NodeIdentity {
     /** Secondary merge key — content hash that catches `id` drift between machines. */
     contentHash: string;
 }
+/**
+ * A value that may be produced synchronously (SQLite, `better-sqlite3`) or
+ * asynchronously (a graph DB over the async Bolt driver, 4.3). The ingest core
+ * `await`s every backend call, so a sync implementation incurs no overhead and the
+ * SQLite path stays byte-for-byte synchronous.
+ */
+type Awaitable<T> = T | Promise<T>;
 /**
  * A provider-agnostic central store. All operations are scoped to a single tenant
- * (`org`); there is no cross-tenant read or write path.
+ * (`org`); there is no cross-tenant read or write path. Methods are **async-capable**
+ * (4.3): `SqliteStoreBackend` returns synchronously, `GraphStoreBackend` returns
+ * Promises; consumers await either.
  */
 interface StoreBackend {
     /**
@@ -1480,15 +1489,15 @@ interface StoreBackend {
      * `'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';
+    upsertNode(org: string, node: DiscoveryNode, identity: NodeIdentity, contributor: Contributor): Awaitable<'created' | 'merged'>;
     /** Insert an edge under `org` (idempotent on the logical `(source, target, relationship)` key). */
-    insertEdge(org: string, edge: DiscoveryEdge): void;
+    insertEdge(org: string, edge: DiscoveryEdge): Awaitable<void>;
     /** Org-wide aggregate summary (merged counts across all contributors). */
-    getSummary(org: string): OrgSummary;
+    getSummary(org: string): Awaitable<OrgSummary>;
     /** Contributors for a merged logical node (test/audit helper). */
-    getContributors(globalId: string): Contributor[];
+    getContributors(globalId: string): Awaitable<Contributor[]>;
     /** Release any underlying resources. */
-    close(): void;
+    close(): Awaitable<void>;
 }
 
 /**
@@ -1519,6 +1528,76 @@ declare class SqliteStoreBackend implements StoreBackend {
     close(): void;
 }
 
+/**
+ * `GraphStoreBackend` (4.3) — an opt-in central-store backend over a Bolt-speaking
+ * graph database (Neo4j / Memgraph). Implements the async-capable {@link StoreBackend}
+ * seam so the central collector's merge + org-summary path can scale to 10K+ nodes on a
+ * native graph engine, while SQLite stays the zero-config default.
+ *
+ * `neo4j-driver` is an OPTIONAL dependency, dynamically imported by `openStoreBackend`
+ * (`src/store/index.ts`); this module depends only on a minimal structural Bolt interface,
+ * so it compiles and the package degrades gracefully when the driver is absent. The driver
+ * is injected (constructor), which also lets tests drive it with a mock — no live DB in CI.
+ *
+ * Merge identity mirrors SQLite: a logical node is keyed by `(org, globalId)`; the
+ * `contentHash` is stored + indexed for the id-drift secondary collapse (best-effort here,
+ * tracked as a follow-up). Contributors are `(org, globalId, machineId)` with max-confidence.
+ */
+
+interface BoltRecord {
+    get(key: string): unknown;
+}
+interface BoltResult {
+    records: BoltRecord[];
+}
+interface BoltSession {
+    run(cypher: string, params?: Record<string, unknown>): Promise<BoltResult>;
+    close(): Promise<void>;
+}
+interface BoltDriver {
+    session(): BoltSession;
+    close(): Promise<void>;
+    verifyConnectivity?(): Promise<unknown>;
+}
+declare class GraphStoreBackend implements StoreBackend {
+    private readonly driver;
+    constructor(driver: BoltDriver);
+    private run;
+    upsertNode(org: string, node: DiscoveryNode, identity: NodeIdentity, contributor: Contributor): Promise<'created' | 'merged'>;
+    insertEdge(org: string, edge: DiscoveryEdge): Promise<void>;
+    getSummary(org: string): Promise<OrgSummary>;
+    getContributors(globalId: string): Promise<Contributor[]>;
+    close(): Promise<void>;
+}
+
+/**
+ * Central-store backend factory (4.3).
+ *
+ * `openStoreBackend` returns a {@link GraphStoreBackend} only when a graph backend is
+ * explicitly requested AND the optional `neo4j-driver` is installed AND the server is
+ * reachable; otherwise it logs a structured WARN and returns the always-available
+ * {@link SqliteStoreBackend}. A missing driver or an unreachable graph server therefore
+ * NEVER breaks the collector — it degrades to SQLite (the "optional deps degrade" locked
+ * constraint). SQLite stays the zero-config default.
+ */
+
+interface StoreBackendOptions {
+    /** `'graph'` opts into the graph DB; anything else (default) uses SQLite. */
+    backend?: 'sqlite' | 'graph';
+    /** Bolt URL, e.g. `bolt://graph.internal:7687` or `neo4j+s://…`. */
+    graphUrl?: string;
+    graphUser?: string;
+    graphPassword?: string;
+    /** Injected driver factory (tests). Defaults to dynamically importing `neo4j-driver`. */
+    driverFactory?: (url: string, user: string, password: string) => Promise<BoltDriver>;
+}
+/**
+ * Resolve the central store backend. Graph when requested + available; else SQLite.
+ * The returned backend is owned by the caller (call `close()` on shutdown for the graph
+ * backend; the SQLite backend's `close()` is a no-op — the `CartographyDB` is shared).
+ */
+declare function openStoreBackend(db: CartographyDB, opts?: StoreBackendOptions): Promise<StoreBackend>;
+
 /**
  * `QueryBackend` — the **read-only** query seam for the API server (4.2).
  *
@@ -1770,7 +1849,7 @@ interface IngestOptions {
  * 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;
+declare function ingestEnvelope(store: StoreBackend, envelope: IngestEnvelope, opts?: IngestOptions): Promise<IngestResult>;
 
 /**
  * Ingest backpressure for the central collector (4.7).
@@ -1825,7 +1904,7 @@ interface IngestResponse {
     /** Extra response headers (e.g. `Retry-After` on a 429). */
     headers?: Record<string, string>;
 }
-type IngestHandler = (body: unknown) => IngestResponse;
+type IngestHandler = (body: unknown) => Promise<IngestResponse>;
 interface IngestHandlerOptions extends IngestOptions {
     /** Per-org ingest rate limiter (4.7 backpressure). Over-quota → 429 + Retry-After. */
     quota?: RateLimiter;
@@ -2186,6 +2265,12 @@ interface CreateMcpServerOptions {
      * behaviour exactly. The org is normalized to a tenant.
      */
     org?: string;
+    /**
+     * Org-wide summary source (4.3). When set (server-mode with a graph backend), the
+     * org `get_summary` reads from here instead of `db.getOrgSummary` — so a graph-DB
+     * collector serves its own merged aggregate. Defaults to the SQLite central store.
+     */
+    orgSummary?: (org: string) => OrgSummary | Promise<OrgSummary>;
     /**
      * The authenticated principal (4.5 RBAC). When set, mutating tools (`run_discovery`)
      * are gated by role: a `viewer` is refused with a forbidden error. Read tools are
@@ -2229,7 +2314,11 @@ interface HttpOptions {
      * 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) => {
+    onIngest?: (body: unknown) => Promise<{
+        status: number;
+        body: unknown;
+        headers?: Record<string, string>;
+    }> | {
         status: number;
         body: unknown;
         headers?: Record<string, string>;
@@ -4186,4 +4275,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 { ACTIONS, ANOMALY_KINDS, ANOMALY_SEVERITIES, type Action, ActionSchema, 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 AuthConfig, AuthConfigSchema, AuthorizationError, type BackstageEntity, type BackstageMapOptions, 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 CredentialConfig, CredentialConfigSchema, type CredentialDb, type CredentialRecord, type CredentialStore, type CronFields, CsvCostSource, type CsvCostSourceOptions, DEFAULT_ANOMALY_THRESHOLDS, DEFAULT_FAST_MODEL, DEFAULT_INGEST_QUOTA, 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 FetchLike, type FragmentKind, type GraphSummary, type HealthResult, type HttpOptions, INGEST_SCHEMA_VERSION, type IngestEnvelope, IngestEnvelopeSchema, type IngestHandler, type IngestHandlerOptions, type IngestOptions, type IngestResponse, type IngestResult, type InstallPlan, InvalidTenantError, type JiraIssue, type JiraOptions, JiraSink, type JiraSinkOptions, 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, PAGERDUTY_ENQUEUE_URL, PENDING_STATUSES, PERSONAL, PORT_MAP, PRIVATE_IP, PUSH_SCHEMA_VERSION, type PagerDutyEvent, PagerDutySink, type PagerDutySinkOptions, type ParsedApiArgs, type PendingShareRow, type PendingStatus, type PlanOptions, type PolicyResult, type PostJsonOptions, type Principal, PrincipalSchema, type ProviderFactory, type ProviderName, ProviderRegistry, type PushItem, type PushOptions, type PushResult, type QueryBackend, type QuotaConfig, type QuotaDecision, RELATION_TO_DIRECTION, ROLES, RateLimiter, type ResolveContext, type ResolveOptions, type Role, RoleSchema, type RuleCheck, RuleCheckSchema, type RuleScope, type Ruleset, RulesetSchema, type RunDriftOptions, SCAN_ARG_PATTERNS, SCHEMA_VERSION, 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, type SlackMessage, SlackSink, SqliteCredentialStore, SqliteQueryBackend, SqliteStoreBackend, type StartApiOptions, StdoutSink, type StoreBackend, type SyncClassifyOptions, type SyncClassifyResult, TENANT_HEADER, type TenantContext, TenantMismatchError, type TenantOptions, type ToolResult, type TopologyDelta, type TopologyDiff, type TopologyInput, type TraversalResult, VectorStore, WebhookSink, type WebhookSinkOptions, applyInstall, applySharingLevel, assertReadOnly, assertSafeBind, assertSafeScanArg, assertSameTenant, assignColors, authorize, bearerToken, bookmarksScanner, buildCartographyToolHandlers, buildMapData, buildOpenApiDocument, buildReport, buildSinks, can, 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, entitiesToYaml, evaluateCheck, evaluateRule, evidenceLine, executeGraphql, executeNlQuery, exportAll, exportBackstageYAML, exportComplianceReport, exportCostCSV, exportCostSummary, exportDiscoveryApp, exportJGF, exportJSON, extractListeningPorts, filterBySeverity, findAnonViolations, formatComplianceText, formatJira, formatPagerDuty, formatSlack, generateDependencyMermaid, generateDiffMermaid, generateTopologyMermaid, getClient, getRuleset, globalId, groupByDomain, handleGraphqlGet, hashToken, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, hmacKey, hostname, ingestEnvelope, installedAppsScanner, isLoopbackHost, isPersonalHost, isReadOnlyCommand, isRemembered, isSecureWebhookUrl, 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, postJson, previewShare, pseudonymize, pseudonymizeFragment, pseudonymizeString, pushDeltas, readConfigFile, redactConnectionString, redactSecrets, redactValue, renderDiff, resolveEffectiveLevel, resolveNlQuery, resolvePrincipal, resolveSharingLevel, resolveTenant, revalidateAnonymized, reversalKey, reversePseudonym, rotateOrgKey, runApi, runDiscovery, runDrift, runHttp, runLocalDiscovery, runOnce, runStdio, runSyncClassify, safeEnv, safeJson, safetyHook, sanitizeUntrusted, sanitizeValue, scopeReads, scoreTopology, securityRelevantChange, serializeConfig, serviceConfigScanner, setVerbose, shadeVariant, shapeToJsonSchema, shareHash, splitSegments, stableStringify, startApi, stripSensitive, timingSafeEqual, toBackstageEntities, validateScanner, vscodeDeeplink, zodToJsonSchema };
+export { ACTIONS, ANOMALY_KINDS, ANOMALY_SEVERITIES, type Action, ActionSchema, 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 AuthConfig, AuthConfigSchema, AuthorizationError, type Awaitable, type BackstageEntity, type BackstageMapOptions, type BindGuardOptions, type BoltDriver, type BoltRecord, type BoltResult, type BoltSession, 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 CredentialConfig, CredentialConfigSchema, type CredentialDb, type CredentialRecord, type CredentialStore, type CronFields, CsvCostSource, type CsvCostSourceOptions, DEFAULT_ANOMALY_THRESHOLDS, DEFAULT_FAST_MODEL, DEFAULT_INGEST_QUOTA, 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 FetchLike, type FragmentKind, GraphStoreBackend, type GraphSummary, type HealthResult, type HttpOptions, INGEST_SCHEMA_VERSION, type IngestEnvelope, IngestEnvelopeSchema, type IngestHandler, type IngestHandlerOptions, type IngestOptions, type IngestResponse, type IngestResult, type InstallPlan, InvalidTenantError, type JiraIssue, type JiraOptions, JiraSink, type JiraSinkOptions, 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, PAGERDUTY_ENQUEUE_URL, PENDING_STATUSES, PERSONAL, PORT_MAP, PRIVATE_IP, PUSH_SCHEMA_VERSION, type PagerDutyEvent, PagerDutySink, type PagerDutySinkOptions, type ParsedApiArgs, type PendingShareRow, type PendingStatus, type PlanOptions, type PolicyResult, type PostJsonOptions, type Principal, PrincipalSchema, type ProviderFactory, type ProviderName, ProviderRegistry, type PushItem, type PushOptions, type PushResult, type QueryBackend, type QuotaConfig, type QuotaDecision, RELATION_TO_DIRECTION, ROLES, RateLimiter, type ResolveContext, type ResolveOptions, type Role, RoleSchema, type RuleCheck, RuleCheckSchema, type RuleScope, type Ruleset, RulesetSchema, type RunDriftOptions, SCAN_ARG_PATTERNS, SCHEMA_VERSION, 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, type SlackMessage, SlackSink, SqliteCredentialStore, SqliteQueryBackend, SqliteStoreBackend, type StartApiOptions, StdoutSink, type StoreBackend, type StoreBackendOptions, type SyncClassifyOptions, type SyncClassifyResult, TENANT_HEADER, type TenantContext, TenantMismatchError, type TenantOptions, type ToolResult, type TopologyDelta, type TopologyDiff, type TopologyInput, type TraversalResult, VectorStore, WebhookSink, type WebhookSinkOptions, applyInstall, applySharingLevel, assertReadOnly, assertSafeBind, assertSafeScanArg, assertSameTenant, assignColors, authorize, bearerToken, bookmarksScanner, buildCartographyToolHandlers, buildMapData, buildOpenApiDocument, buildReport, buildSinks, can, 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, entitiesToYaml, evaluateCheck, evaluateRule, evidenceLine, executeGraphql, executeNlQuery, exportAll, exportBackstageYAML, exportComplianceReport, exportCostCSV, exportCostSummary, exportDiscoveryApp, exportJGF, exportJSON, extractListeningPorts, filterBySeverity, findAnonViolations, formatComplianceText, formatJira, formatPagerDuty, formatSlack, generateDependencyMermaid, generateDiffMermaid, generateTopologyMermaid, getClient, getRuleset, globalId, groupByDomain, handleGraphqlGet, hashToken, hexCorners, hexDistance, hexNeighbors, hexRing, hexSpiral, hexToPixel, hmacKey, hostname, ingestEnvelope, installedAppsScanner, isLoopbackHost, isPersonalHost, isReadOnlyCommand, isRemembered, isSecureWebhookUrl, k8sScanner, keyMetaOf, layoutClusters, listClients, listRulesets, loadConfig, loadOrgKey, loadPlugins, loadRuleset, localDiscoveryFn, log, logDebug, logError, logInfo, logWarn, machineId, maxSeverity, mcpServerObject, newAnomalies, nextRun, nodesToAssets, normalizeId, normalizeTenant, openStoreBackend, orgKeyPath, osUser, parseApiArgs, parseComposeDeps, parseConfig, parseConnectionString, parseCostCsv, parseCron, parseEstablished, parseNginxUpstreams, parseNlQuery, parseScanHint, pixelToHex, planInstall, portsScanner, postJson, previewShare, pseudonymize, pseudonymizeFragment, pseudonymizeString, pushDeltas, readConfigFile, redactConnectionString, redactSecrets, redactValue, renderDiff, resolveEffectiveLevel, resolveNlQuery, resolvePrincipal, resolveSharingLevel, resolveTenant, revalidateAnonymized, reversalKey, reversePseudonym, rotateOrgKey, runApi, runDiscovery, runDrift, runHttp, runLocalDiscovery, runOnce, runStdio, runSyncClassify, safeEnv, safeJson, safetyHook, sanitizeUntrusted, sanitizeValue, scopeReads, scoreTopology, securityRelevantChange, serializeConfig, serviceConfigScanner, setVerbose, shadeVariant, shapeToJsonSchema, shareHash, splitSegments, stableStringify, startApi, stripSensitive, timingSafeEqual, toBackstageEntities, validateScanner, vscodeDeeplink, zodToJsonSchema };

package/dist/index.js

@@ -4362,6 +4362,148 @@ var SqliteStoreBackend = class {
   }
 };
 
+// src/store/graph.ts
+function toNum(v) {
+  if (typeof v === "number") return v;
+  if (v && typeof v === "object" && "toNumber" in v && typeof v.toNumber === "function") {
+    return v.toNumber();
+  }
+  return Number(v ?? 0);
+}
+var GraphStoreBackend = class {
+  constructor(driver) {
+    this.driver = driver;
+  }
+  async run(cypher, params) {
+    const session = this.driver.session();
+    try {
+      return await session.run(cypher, params);
+    } finally {
+      await session.close();
+    }
+  }
+  async upsertNode(org, node, identity, contributor) {
+    const res = await this.run(
+      `MERGE (n:Node {org: $org, globalId: $globalId})
+       ON CREATE SET n._created = true
+       ON MATCH  SET n._created = false
+       SET n.id = $id, n.contentHash = $contentHash, n.type = $type, n.name = $name,
+           n.domain = $domain, n.owner = $owner,
+           n.confidence = CASE WHEN n.confidence IS NULL OR $confidence > n.confidence THEN $confidence ELSE n.confidence END
+       MERGE (c:Contributor {org: $org, globalId: $globalId, machineId: $machineId})
+       SET c.hostname = $hostname, c.user = $user, c.at = $at,
+           c.confidence = CASE WHEN c.confidence IS NULL OR $contribConfidence > c.confidence THEN $contribConfidence ELSE c.confidence END
+       RETURN n._created AS created`,
+      {
+        org,
+        globalId: identity.globalId,
+        contentHash: identity.contentHash,
+        id: node.id,
+        type: node.type,
+        name: node.name,
+        domain: node.domain ?? null,
+        owner: node.owner ?? null,
+        confidence: node.confidence,
+        machineId: contributor.machineId,
+        hostname: contributor.hostname,
+        user: contributor.user,
+        at: contributor.at,
+        contribConfidence: contributor.confidence
+      }
+    );
+    return res.records[0]?.get("created") === true ? "created" : "merged";
+  }
+  async insertEdge(org, edge) {
+    await this.run(
+      `MATCH (s:Node {org: $org, id: $source})
+       MATCH (t:Node {org: $org, id: $target})
+       MERGE (s)-[r:DEPENDS {relationship: $rel}]->(t)
+       SET r.evidence = $evidence, r.confidence = $confidence`,
+      { org, source: edge.sourceId, target: edge.targetId, rel: edge.relationship, evidence: edge.evidence, confidence: edge.confidence }
+    );
+  }
+  async getSummary(org) {
+    const totals = await this.run(
+      `MATCH (n:Node {org: $org})
+       OPTIONAL MATCH (n)-[r:DEPENDS]->(:Node {org: $org})
+       RETURN count(DISTINCT n) AS nodes, count(r) AS edges`,
+      { org }
+    );
+    const byType = await this.run(`MATCH (n:Node {org: $org}) RETURN n.type AS k, count(*) AS c`, { org });
+    const byDomain = await this.run(`MATCH (n:Node {org: $org}) RETURN coalesce(n.domain, '(none)') AS k, count(*) AS c`, { org });
+    const byRel = await this.run(`MATCH (:Node {org: $org})-[r:DEPENDS]->(:Node {org: $org}) RETURN r.relationship AS k, count(*) AS c`, { org });
+    const top = await this.run(
+      `MATCH (n:Node {org: $org})
+       OPTIONAL MATCH (n)-[r:DEPENDS]-(:Node {org: $org})
+       RETURN n.id AS id, n.name AS name, n.type AS type, count(r) AS degree
+       ORDER BY degree DESC, id ASC LIMIT 10`,
+      { org }
+    );
+    const contrib = await this.run(`MATCH (c:Contributor {org: $org}) RETURN count(DISTINCT c.machineId) AS contributors`, { org });
+    const counts = (r) => {
+      const out = {};
+      for (const rec of r.records) out[String(rec.get("k"))] = toNum(rec.get("c"));
+      return out;
+    };
+    return {
+      org,
+      totals: { nodes: toNum(totals.records[0]?.get("nodes")), edges: toNum(totals.records[0]?.get("edges")) },
+      nodesByType: counts(byType),
+      nodesByDomain: counts(byDomain),
+      edgesByRelationship: counts(byRel),
+      topConnected: top.records.map((rec) => ({
+        id: String(rec.get("id")),
+        name: String(rec.get("name")),
+        type: String(rec.get("type")),
+        degree: toNum(rec.get("degree"))
+      })),
+      contributors: toNum(contrib.records[0]?.get("contributors"))
+    };
+  }
+  async getContributors(globalId2) {
+    const res = await this.run(
+      `MATCH (c:Contributor {globalId: $globalId})
+       RETURN c.machineId AS machineId, c.hostname AS hostname, c.user AS user, c.org AS org, c.at AS at, c.confidence AS confidence`,
+      { globalId: globalId2 }
+    );
+    return res.records.map((rec) => ({
+      machineId: String(rec.get("machineId")),
+      hostname: String(rec.get("hostname")),
+      user: String(rec.get("user")),
+      organization: rec.get("org") != null ? String(rec.get("org")) : void 0,
+      at: String(rec.get("at")),
+      confidence: toNum(rec.get("confidence"))
+    }));
+  }
+  async close() {
+    await this.driver.close();
+  }
+};
+
+// src/store/index.ts
+async function defaultNeo4jDriver(url, user, password) {
+  const mod = await import("neo4j-driver");
+  return mod.default.driver(url, mod.default.auth.basic(user, password));
+}
+async function openStoreBackend(db, opts = {}) {
+  if (opts.backend === "graph" && opts.graphUrl) {
+    try {
+      const make = opts.driverFactory ?? defaultNeo4jDriver;
+      const driver = await make(opts.graphUrl, opts.graphUser ?? "neo4j", opts.graphPassword ?? "");
+      if (driver.verifyConnectivity) await driver.verifyConnectivity();
+      logInfo("central store: graph backend active", { host: stripSensitive(opts.graphUrl) });
+      return new GraphStoreBackend(driver);
+    } catch (err) {
+      logWarn("central store: graph backend unavailable \u2014 falling back to SQLite", {
+        host: stripSensitive(opts.graphUrl),
+        reason: err instanceof Error ? err.message : String(err)
+      });
+      return new SqliteStoreBackend(db);
+    }
+  }
+  return new SqliteStoreBackend(db);
+}
+
 // src/store/query.ts
 var NotFoundError = class extends Error {
   constructor(message) {
@@ -4676,9 +4818,9 @@ var IngestEnvelopeSchema = z5.object({
   contributor: ContributorSchema.optional(),
   anonymizationLevel: z5.enum(["none", "anonymized", "full"]).optional()
 });
-function ingestEnvelope(store, envelope, opts = {}) {
+async function ingestEnvelope(store, envelope, opts = {}) {
   const anonMode = opts.anonMode ?? "reject";
-  const org = envelope.org ?? opts.defaultOrg ?? "local";
+  const org = normalizeTenant(envelope.org ?? opts.defaultOrg);
   const level = envelope.anonymizationLevel ?? "anonymized";
   const at = (/* @__PURE__ */ new Date()).toISOString();
   const contributor = {
@@ -4729,7 +4871,7 @@ function ingestEnvelope(store, envelope, opts = {}) {
     }
     const safe = check.node;
     const identity = computeIdentity(org, safe);
-    const outcome = store.upsertNode(org, safe, identity, { ...contributor, confidence: safe.confidence });
+    const outcome = await store.upsertNode(org, safe, identity, { ...contributor, confidence: safe.confidence });
     accepted += 1;
     if (outcome === "merged") merged += 1;
     acceptedNodeIds.add(safe.id);
@@ -4745,7 +4887,7 @@ function ingestEnvelope(store, envelope, opts = {}) {
     if (acceptedNodeIds.size > 0 && (!acceptedNodeIds.has(edge.sourceId) || !acceptedNodeIds.has(edge.targetId))) {
       continue;
     }
-    store.insertEdge(org, edge);
+    await store.insertEdge(org, edge);
     edges += 1;
   }
   logInfo("ingest", { org, accepted, merged, rejected, edges, violations, level, anonMode });
@@ -4755,7 +4897,7 @@ function ingestEnvelope(store, envelope, opts = {}) {
 // src/central/server.ts
 function createIngestHandler(store, opts = {}) {
   const quota = opts.quota;
-  return (body) => {
+  return async (body) => {
     const parsed = IngestEnvelopeSchema.safeParse(body);
     if (!parsed.success) {
       const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`);
@@ -4771,7 +4913,7 @@ function createIngestHandler(store, opts = {}) {
       }
     }
     try {
-      const result = ingestEnvelope(store, parsed.data, opts);
+      const result = await ingestEnvelope(store, parsed.data, opts);
       return { status: 200, body: result };
     } catch (err) {
       logWarn("ingest: failed", { error: err instanceof Error ? err.message : String(err) });
@@ -5700,7 +5842,7 @@ async function resolveNlQuery(db, sessionId, search, raw, opts) {
 
 // src/mcp/server.ts
 var SERVER_NAME = "cartography";
-var SERVER_VERSION = "2.7.0";
+var SERVER_VERSION = "2.8.0";
 var SERVICE_TYPES = NODE_TYPE_GROUPS.web;
 var DATA_TYPES = NODE_TYPE_GROUPS.data;
 var lexicalSearch = async (db, sessionId, query, opts) => db.searchNodes(sessionId, query, { types: opts.types, limit: opts.limit }).map((node) => ({ node }));
@@ -5775,9 +5917,10 @@ function createMcpServer(opts = {}) {
     "graph-summary",
     "cartography://graph/summary",
     { title: "Topology summary", description: "Low-token aggregate index of the whole landscape \u2014 read this first.", mimeType: "text/markdown" },
-    (uri) => {
+    async (uri) => {
       if (org !== void 0) {
-        return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: summaryText(db.getOrgSummary(org)) }] };
+        const s = opts.orgSummary ? await opts.orgSummary(org) : db.getOrgSummary(org);
+        return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: summaryText(s) }] };
       }
       const sid = resolveSession();
       if (!sid) return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: "No discovery session found. Run discovery first." }] };
@@ -5852,8 +5995,8 @@ function createMcpServer(opts = {}) {
   server.registerTool(
     "get_summary",
     { title: "Get topology summary", description: "Low-token overview of the whole landscape (counts, types, domains, most-connected, anomalies).", inputSchema: {}, annotations: readOnly },
-    () => {
-      if (org !== void 0) return json(db.getOrgSummary(org));
+    async () => {
+      if (org !== void 0) return json(opts.orgSummary ? await opts.orgSummary(org) : db.getOrgSummary(org));
       const sid = resolveSession();
       if (!sid) return json({ error: "No discovery session found." });
       return json(db.getGraphSummary(sid));
@@ -6379,7 +6522,7 @@ async function runHttp(factory, opts = {}) {
           res.writeHead(413, { "content-type": "application/json" }).end('{"error":"payload too large"}');
           return;
         }
-        const out = onIngest(value);
+        const out = await onIngest(value);
         res.writeHead(out.status, { "content-type": "application/json", ...out.headers ?? {} }).end(JSON.stringify(out.body));
         return;
       }
@@ -11634,6 +11777,7 @@ export {
   DEFAULT_SERVER_NAME,
   DEFAULT_TENANT,
   DriftConfigSchema,
+  GraphStoreBackend,
   INGEST_SCHEMA_VERSION,
   IngestEnvelopeSchema,
   InvalidTenantError,
@@ -11805,6 +11949,7 @@ export {
   nodesToAssets,
   normalizeId,
   normalizeTenant,
+  openStoreBackend,
   orgKeyPath,
   osUser,
   parseApiArgs,