@neat.is/core 0.6.3 → 0.7.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { MultiDirectedGraph } from 'graphology';
-import { GraphNode, GraphEdge, StaleEvent, ErrorEvent, BlastRadiusResult, RootCauseResult, EdgeTypeValue, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
+import { GraphNode, GraphEdge, EdgeTypeValue, StaleEvent, ErrorEvent, BlastRadiusResult, RootCauseResult, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
 export { StaleEvent } from '@neat.is/types';
 import { FastifyInstance } from 'fastify';
 
@@ -110,6 +110,123 @@ declare class Projects {
     attachSearchIndex(name: string, index: SearchIndex | undefined): void;
 }
 
+/**
+ * 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;
+    /**
+     * Set when `targetNodeId` names an InfraNode no static extractor has (yet)
+     * declared — the honest "observed but undeclared" fallback
+     * (docs/contracts/connectors.md §4a, ADR-133). A provider's `resolveTarget`
+     * has no mutation authority of its own (ADR-030), so it declares the need
+     * here instead of creating the node itself; the generic pipeline below
+     * calls `ensureInfraNode` before minting the edge. `targetNodeId` MUST equal
+     * `infraId(kind, name)` when this is set.
+     */
+    ensureInfraNode?: {
+        kind: string;
+        name: string;
+        provider: string;
+    };
+}
+type ResolveConnectorTarget = (signal: ObservedSignal, ctx: ConnectorContext) => ResolvedConnectorTarget | null;
+interface ConnectorPollResult {
+    signalCount: number;
+    edgesCreated: number;
+    edgesUpdated: number;
+    unresolved: number;
+}
+/**
+ * One poll cycle: fetch, map, fuse, mint. Pure with respect to `ctx` — the
+ * caller (`startConnectorPollLoop` below, or a one-shot `neat sync`) owns
+ * advancing `ctx.since` between calls.
+ */
+declare function runConnectorPoll(connector: ObservedConnector, ctx: ConnectorContext, graph: NeatGraph, resolveTarget: ResolveConnectorTarget): Promise<ConnectorPollResult>;
+/**
+ * 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 {
+    id?: string;
+    connector: ObservedConnector;
+    credentials: Record<string, unknown>;
+    resolveTarget: ResolveConnectorTarget;
+    intervalMs?: number;
+}
+
 interface BuildApiOptions {
     projects?: Projects;
     startedAt?: number;
@@ -134,6 +251,7 @@ interface BuildApiOptions {
         path: string;
     };
     connectorsHome?: string;
+    runPoll?: typeof runConnectorPoll;
 }
 declare function buildApi(opts: BuildApiOptions): Promise<FastifyInstance>;
 
@@ -349,111 +467,6 @@ 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;
-    /**
-     * Set when `targetNodeId` names an InfraNode no static extractor has (yet)
-     * declared — the honest "observed but undeclared" fallback
-     * (docs/contracts/connectors.md §4a, ADR-133). A provider's `resolveTarget`
-     * has no mutation authority of its own (ADR-030), so it declares the need
-     * here instead of creating the node itself; the generic pipeline below
-     * calls `ensureInfraNode` before minting the edge. `targetNodeId` MUST equal
-     * `infraId(kind, name)` when this is set.
-     */
-    ensureInfraNode?: {
-        kind: string;
-        name: string;
-        provider: string;
-    };
-}
-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 {
-    id?: string;
-    connector: ObservedConnector;
-    credentials: Record<string, unknown>;
-    resolveTarget: ResolveConnectorTarget;
-    intervalMs?: number;
-}
-
 /**
  * Multi-project daemon (ADR-049).
  *

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { MultiDirectedGraph } from 'graphology';
-import { GraphNode, GraphEdge, StaleEvent, ErrorEvent, BlastRadiusResult, RootCauseResult, EdgeTypeValue, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
+import { GraphNode, GraphEdge, EdgeTypeValue, StaleEvent, ErrorEvent, BlastRadiusResult, RootCauseResult, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
 export { StaleEvent } from '@neat.is/types';
 import { FastifyInstance } from 'fastify';
 
@@ -110,6 +110,123 @@ declare class Projects {
     attachSearchIndex(name: string, index: SearchIndex | undefined): void;
 }
 
+/**
+ * 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;
+    /**
+     * Set when `targetNodeId` names an InfraNode no static extractor has (yet)
+     * declared — the honest "observed but undeclared" fallback
+     * (docs/contracts/connectors.md §4a, ADR-133). A provider's `resolveTarget`
+     * has no mutation authority of its own (ADR-030), so it declares the need
+     * here instead of creating the node itself; the generic pipeline below
+     * calls `ensureInfraNode` before minting the edge. `targetNodeId` MUST equal
+     * `infraId(kind, name)` when this is set.
+     */
+    ensureInfraNode?: {
+        kind: string;
+        name: string;
+        provider: string;
+    };
+}
+type ResolveConnectorTarget = (signal: ObservedSignal, ctx: ConnectorContext) => ResolvedConnectorTarget | null;
+interface ConnectorPollResult {
+    signalCount: number;
+    edgesCreated: number;
+    edgesUpdated: number;
+    unresolved: number;
+}
+/**
+ * One poll cycle: fetch, map, fuse, mint. Pure with respect to `ctx` — the
+ * caller (`startConnectorPollLoop` below, or a one-shot `neat sync`) owns
+ * advancing `ctx.since` between calls.
+ */
+declare function runConnectorPoll(connector: ObservedConnector, ctx: ConnectorContext, graph: NeatGraph, resolveTarget: ResolveConnectorTarget): Promise<ConnectorPollResult>;
+/**
+ * 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 {
+    id?: string;
+    connector: ObservedConnector;
+    credentials: Record<string, unknown>;
+    resolveTarget: ResolveConnectorTarget;
+    intervalMs?: number;
+}
+
 interface BuildApiOptions {
     projects?: Projects;
     startedAt?: number;
@@ -134,6 +251,7 @@ interface BuildApiOptions {
         path: string;
     };
     connectorsHome?: string;
+    runPoll?: typeof runConnectorPoll;
 }
 declare function buildApi(opts: BuildApiOptions): Promise<FastifyInstance>;
 
@@ -349,111 +467,6 @@ 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;
-    /**
-     * Set when `targetNodeId` names an InfraNode no static extractor has (yet)
-     * declared — the honest "observed but undeclared" fallback
-     * (docs/contracts/connectors.md §4a, ADR-133). A provider's `resolveTarget`
-     * has no mutation authority of its own (ADR-030), so it declares the need
-     * here instead of creating the node itself; the generic pipeline below
-     * calls `ensureInfraNode` before minting the edge. `targetNodeId` MUST equal
-     * `infraId(kind, name)` when this is set.
-     */
-    ensureInfraNode?: {
-        kind: string;
-        name: string;
-        provider: string;
-    };
-}
-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 {
-    id?: string;
-    connector: ObservedConnector;
-    credentials: Record<string, unknown>;
-    resolveTarget: ResolveConnectorTarget;
-    intervalMs?: number;
-}
-
 /**
  * Multi-project daemon (ADR-049).
  *

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   routeSpanToProject,
   startDaemon
-} from "./chunk-PWIT35Z4.js";
+} from "./chunk-UBQ4ZZT3.js";
 import {
   ProjectNameCollisionError,
   addProject,
@@ -37,15 +37,15 @@ import {
   thresholdForEdgeType,
   touchLastSeen,
   writeAtomically
-} from "./chunk-L64CATKE.js";
+} from "./chunk-5RIL3U5A.js";
 import {
   startOtelGrpcReceiver
-} from "./chunk-7QXN726V.js";
+} from "./chunk-Q6DPK3RA.js";
 import {
   buildOtelReceiver,
   logSpanHandler,
   parseOtlpRequest
-} from "./chunk-ZLAZ7PLC.js";
+} from "./chunk-N5L3RBGP.js";
 export {
   ProjectNameCollisionError,
   addProject,