@neat.is/core 0.4.26-dev.20260703 → 0.4.27-dev.20260705

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { MultiDirectedGraph } from 'graphology';
-import { GraphNode, GraphEdge, StaleEvent, ErrorEvent, BlastRadiusResult, RootCauseResult, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
+import { GraphNode, GraphEdge, StaleEvent, ErrorEvent, BlastRadiusResult, RootCauseResult, EdgeTypeValue, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
 export { StaleEvent } from '@neat.is/types';
 import { FastifyInstance } from 'fastify';
 
@@ -156,6 +156,10 @@ interface ParsedSpan {
     messagingDestination?: string;
     graphqlOperationName?: string;
     graphqlOperationType?: string;
+    rpcSystem?: string;
+    rpcService?: string;
+    rpcMethod?: string;
+    websocketChannel?: string;
     statusCode?: number;
     errorMessage?: string;
     exception?: {
@@ -339,6 +343,96 @@ interface GraphDiff {
 declare function loadSnapshotForDiff(target: string): Promise<PersistedSnapshot>;
 declare function computeGraphDiff(liveGraph: NeatGraph, baseSnapshot: PersistedSnapshot, currentExportedAt?: string): GraphDiff;
 
+/**
+ * A connector implements exactly one method. Everything downstream of
+ * `poll()` — resolving a static call site, minting the OBSERVED edge — is
+ * shared, generic code in connectors/index.ts.
+ */
+interface ObservedConnector {
+    readonly provider: string;
+    poll(ctx: ConnectorContext): Promise<ObservedSignal[]>;
+}
+/**
+ * Everything a connector's `poll()` needs, resolved once at connector setup
+ * — never re-derived at poll time.
+ *
+ * `credentials` is opaque here on purpose: its shape is entirely provider-
+ * and profile-defined (local vs hosted — docs/contracts/connectors.md §3).
+ * It flows through to `poll()` only. Never log it, never write it into a
+ * node or edge, never let it reach the graph snapshot (contract §6, and the
+ * `.env`-contents rule docs/contracts.md Rule 4 already states for local
+ * config).
+ */
+interface ConnectorContext {
+    projectDir: string;
+    credentials: Record<string, unknown>;
+    since?: string;
+}
+/**
+ * `file:line` the provider's own signal carries, when it does (rare — see
+ * docs/connectors/README.md §Provider interface, which notes this is
+ * "usually resolved by the mapping layer below, not here"). Reconciled onto
+ * the EXTRACTED service-relative path by the shared fuse step the same way
+ * an OTel span's call site is (file-awareness.md §4).
+ */
+interface ConnectorCallSite {
+    file: string;
+    line: number;
+}
+/**
+ * One provider-agnostic observation. `targetKind`/`targetName` are the
+ * provider's own vocabulary (`'supabase-table'`/`'orders'`,
+ * `'route'`/`'GET /users/:id'`, ...) — resolving that pair to a NEAT node id
+ * is the one genuinely provider-specific step (README.md's pipeline
+ * diagram), supplied to `runConnectorPoll` (connectors/index.ts) as a
+ * `resolveTarget` callback. Everything downstream of that resolution — file
+ * grain fusion, OBSERVED mint — is shared.
+ */
+interface ObservedSignal {
+    targetKind: string;
+    targetName: string;
+    callCount: number;
+    errorCount: number;
+    lastObservedIso: string;
+    callSite?: ConnectorCallSite;
+}
+
+/**
+ * What a provider's target-resolution step hands back for one signal. The
+ * generic pipeline needs both endpoints of the edge it's about to mint:
+ *
+ * - `serviceName` is the NEAT manifest service whose code produced the
+ *   signal — the edge's source. The shared pipeline turns it into a plain
+ *   ServiceNode id, or a FileNode id once the fuse step below resolves the
+ *   signal's callSite against it.
+ * - `targetNodeId` is the id the provider's own mapping already resolved —
+ *   an `infraId(...)` sub-resource, a RouteNode, a ServiceNode, whatever
+ *   (see each provider's docs/connectors/<provider>.md §Fusion).
+ *
+ * Returning `null` skips the signal honestly: an unresolvable target never
+ * fabricates a node or edge (the same discipline file-awareness.md §6
+ * states for OTel ingest).
+ */
+interface ResolvedConnectorTarget {
+    targetNodeId: string;
+    serviceName: string;
+    edgeType: EdgeTypeValue;
+}
+type ResolveConnectorTarget = (signal: ObservedSignal, ctx: ConnectorContext) => ResolvedConnectorTarget | null;
+/**
+ * One project's registered connector, ready for `daemon.ts` to poll on an
+ * interval. Deliberately thin — no config-loading or credential-broker logic
+ * lives here (that's provider- and profile-specific, later work per
+ * docs/contracts/connectors.md §3); this is just the seam a daemon slot
+ * wires a connector through.
+ */
+interface ConnectorRegistration {
+    connector: ObservedConnector;
+    credentials: Record<string, unknown>;
+    resolveTarget: ResolveConnectorTarget;
+    intervalMs?: number;
+}
+
 /**
  * Multi-project daemon (ADR-049).
  *
@@ -390,6 +484,7 @@ interface DaemonOptions {
     otlpPort?: number;
     host?: string;
     bindListeners?: boolean;
+    connectors?: ConnectorRegistration[];
 }
 interface ProjectSlot {
     entry: RegistryEntry;
@@ -398,6 +493,7 @@ interface ProjectSlot {
     paths: ProjectPaths;
     stopPersist: () => void;
     stopStaleness: () => void;
+    stopConnectors: () => void;
     detachEvents: () => void;
     status: 'active' | 'broken';
     errorReason?: string;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { MultiDirectedGraph } from 'graphology';
-import { GraphNode, GraphEdge, StaleEvent, ErrorEvent, BlastRadiusResult, RootCauseResult, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
+import { GraphNode, GraphEdge, StaleEvent, ErrorEvent, BlastRadiusResult, RootCauseResult, EdgeTypeValue, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
 export { StaleEvent } from '@neat.is/types';
 import { FastifyInstance } from 'fastify';
 
@@ -156,6 +156,10 @@ interface ParsedSpan {
     messagingDestination?: string;
     graphqlOperationName?: string;
     graphqlOperationType?: string;
+    rpcSystem?: string;
+    rpcService?: string;
+    rpcMethod?: string;
+    websocketChannel?: string;
     statusCode?: number;
     errorMessage?: string;
     exception?: {
@@ -339,6 +343,96 @@ interface GraphDiff {
 declare function loadSnapshotForDiff(target: string): Promise<PersistedSnapshot>;
 declare function computeGraphDiff(liveGraph: NeatGraph, baseSnapshot: PersistedSnapshot, currentExportedAt?: string): GraphDiff;
 
+/**
+ * A connector implements exactly one method. Everything downstream of
+ * `poll()` — resolving a static call site, minting the OBSERVED edge — is
+ * shared, generic code in connectors/index.ts.
+ */
+interface ObservedConnector {
+    readonly provider: string;
+    poll(ctx: ConnectorContext): Promise<ObservedSignal[]>;
+}
+/**
+ * Everything a connector's `poll()` needs, resolved once at connector setup
+ * — never re-derived at poll time.
+ *
+ * `credentials` is opaque here on purpose: its shape is entirely provider-
+ * and profile-defined (local vs hosted — docs/contracts/connectors.md §3).
+ * It flows through to `poll()` only. Never log it, never write it into a
+ * node or edge, never let it reach the graph snapshot (contract §6, and the
+ * `.env`-contents rule docs/contracts.md Rule 4 already states for local
+ * config).
+ */
+interface ConnectorContext {
+    projectDir: string;
+    credentials: Record<string, unknown>;
+    since?: string;
+}
+/**
+ * `file:line` the provider's own signal carries, when it does (rare — see
+ * docs/connectors/README.md §Provider interface, which notes this is
+ * "usually resolved by the mapping layer below, not here"). Reconciled onto
+ * the EXTRACTED service-relative path by the shared fuse step the same way
+ * an OTel span's call site is (file-awareness.md §4).
+ */
+interface ConnectorCallSite {
+    file: string;
+    line: number;
+}
+/**
+ * One provider-agnostic observation. `targetKind`/`targetName` are the
+ * provider's own vocabulary (`'supabase-table'`/`'orders'`,
+ * `'route'`/`'GET /users/:id'`, ...) — resolving that pair to a NEAT node id
+ * is the one genuinely provider-specific step (README.md's pipeline
+ * diagram), supplied to `runConnectorPoll` (connectors/index.ts) as a
+ * `resolveTarget` callback. Everything downstream of that resolution — file
+ * grain fusion, OBSERVED mint — is shared.
+ */
+interface ObservedSignal {
+    targetKind: string;
+    targetName: string;
+    callCount: number;
+    errorCount: number;
+    lastObservedIso: string;
+    callSite?: ConnectorCallSite;
+}
+
+/**
+ * What a provider's target-resolution step hands back for one signal. The
+ * generic pipeline needs both endpoints of the edge it's about to mint:
+ *
+ * - `serviceName` is the NEAT manifest service whose code produced the
+ *   signal — the edge's source. The shared pipeline turns it into a plain
+ *   ServiceNode id, or a FileNode id once the fuse step below resolves the
+ *   signal's callSite against it.
+ * - `targetNodeId` is the id the provider's own mapping already resolved —
+ *   an `infraId(...)` sub-resource, a RouteNode, a ServiceNode, whatever
+ *   (see each provider's docs/connectors/<provider>.md §Fusion).
+ *
+ * Returning `null` skips the signal honestly: an unresolvable target never
+ * fabricates a node or edge (the same discipline file-awareness.md §6
+ * states for OTel ingest).
+ */
+interface ResolvedConnectorTarget {
+    targetNodeId: string;
+    serviceName: string;
+    edgeType: EdgeTypeValue;
+}
+type ResolveConnectorTarget = (signal: ObservedSignal, ctx: ConnectorContext) => ResolvedConnectorTarget | null;
+/**
+ * One project's registered connector, ready for `daemon.ts` to poll on an
+ * interval. Deliberately thin — no config-loading or credential-broker logic
+ * lives here (that's provider- and profile-specific, later work per
+ * docs/contracts/connectors.md §3); this is just the seam a daemon slot
+ * wires a connector through.
+ */
+interface ConnectorRegistration {
+    connector: ObservedConnector;
+    credentials: Record<string, unknown>;
+    resolveTarget: ResolveConnectorTarget;
+    intervalMs?: number;
+}
+
 /**
  * Multi-project daemon (ADR-049).
  *
@@ -390,6 +484,7 @@ interface DaemonOptions {
     otlpPort?: number;
     host?: string;
     bindListeners?: boolean;
+    connectors?: ConnectorRegistration[];
 }
 interface ProjectSlot {
     entry: RegistryEntry;
@@ -398,6 +493,7 @@ interface ProjectSlot {
     paths: ProjectPaths;
     stopPersist: () => void;
     stopStaleness: () => void;
+    stopConnectors: () => void;
     detachEvents: () => void;
     status: 'active' | 'broken';
     errorReason?: string;

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   routeSpanToProject,
   startDaemon
-} from "./chunk-S7TDPQDD.js";
+} from "./chunk-XV4D7A3Z.js";
 import {
   ProjectNameCollisionError,
   addProject,
@@ -37,15 +37,15 @@ import {
   thresholdForEdgeType,
   touchLastSeen,
   writeAtomically
-} from "./chunk-WZYH5DVG.js";
+} from "./chunk-QM6BMPVJ.js";
 import {
   startOtelGrpcReceiver
-} from "./chunk-C5NCCKPZ.js";
+} from "./chunk-UV5WSM7M.js";
 import {
   buildOtelReceiver,
   logSpanHandler,
   parseOtlpRequest
-} from "./chunk-2LNICOVU.js";
+} from "./chunk-A3322JYS.js";
 export {
   ProjectNameCollisionError,
   addProject,