@neat.is/core 0.10.5 → 0.10.6-dev.20261008

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 import { MultiDirectedGraph } from 'graphology';
-import { GraphNode, GraphEdge, EdgeEvidence, SpanAttributes, EdgeTypeValue, StaleEvent, ErrorEvent, BlastRadiusResult, RootCauseResult, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
+import { GraphNode, GraphEdge, EdgeEvidence, ErrorEvent, SpanAttributes, EdgeTypeValue, StaleEvent, BlastRadiusResult, RootCauseResult, RegistryEntry } from '@neat.is/types';
 export { StaleEvent } from '@neat.is/types';
 import { FastifyInstance } from 'fastify';
+export { ProjectNameCollisionError, addProject, getProject, listProjects, normalizeProjectPath, readRegistry, registryLockPath, registryPath, removeProject, setStatus, touchLastSeen, writeAtomically } from './registry.cjs';
 
 type NeatGraph = MultiDirectedGraph<GraphNode, GraphEdge>;
 declare function getGraph(project?: string): NeatGraph;
@@ -46,6 +47,7 @@ interface ExtractOptions {
     project?: string;
     errorsPath?: string;
     source?: string;
+    announce?: boolean;
 }
 declare function extractFromDirectory(graph: NeatGraph, scanPath: string, opts?: ExtractOptions): Promise<ExtractResult>;
 
@@ -150,6 +152,43 @@ interface RepoSyncRequestResult {
     lastPass?: RepoSyncPassSummary;
 }
 
+interface PrVerdictRequest {
+    owner: string;
+    name: string;
+    baseSha: string;
+    headSha: string;
+    /** `https://x-access-token:<token>@github.com/<owner>/<name>.git`. Used for the two clones, then gone. */
+    cloneUrl: string;
+    /** Repo-relative paths the PR changes, from the caller. Absent → the two trees are compared. */
+    changedFiles?: string[];
+    tone?: 'loud' | 'professional';
+}
+interface PrVerdictResult {
+    marker: string;
+    body: string;
+    base: {
+        sha: string;
+        nodes: number;
+        edges: number;
+    };
+    head: {
+        sha: string;
+        nodes: number;
+        edges: number;
+    };
+    changedFiles: number;
+    observedBreaks: number;
+    divergences: number;
+    durationMs: number;
+}
+interface PrVerdictContext {
+    /** The project's live graph. Read for OBSERVED; never written. */
+    liveGraph: NeatGraph;
+    /** The project's recorded incidents, for symbol-grain divergences — the same read `/graph/divergences` does. */
+    incidents?: ErrorEvent[];
+}
+type PrVerdictRunner = (req: PrVerdictRequest, ctx: PrVerdictContext) => Promise<PrVerdictResult>;
+
 /**
  * A connector implements exactly one method. Everything downstream of
  * `poll()` — resolving a static call site, minting the OBSERVED edge — is
@@ -315,6 +354,9 @@ interface BuildApiOptions {
     staleEventsPath?: string;
     searchIndex?: SearchIndex;
     authToken?: string;
+    incidentStreamToken?: string;
+    /** Set only after the hosted substrate restores the complete errors ledger before boot. */
+    incidentReplayDurable?: boolean;
     trustProxy?: boolean;
     publicRead?: boolean;
     otlpReceiver?: () => FastifyInstance | undefined;
@@ -332,6 +374,7 @@ interface BuildApiOptions {
     };
     connectorsHome?: string;
     repoSync?: (project: string) => (() => RepoSyncRequestResult) | undefined;
+    prVerdict?: PrVerdictRunner;
     runPoll?: typeof runConnectorPoll;
 }
 declare function buildApi(opts: BuildApiOptions): Promise<FastifyInstance>;
@@ -684,101 +727,4 @@ interface DaemonHandle {
 declare function routeSpanToProject(serviceName: string | undefined, projects: ReadonlyArray<RegistryEntry>): string;
 declare function startDaemon(opts?: DaemonOptions): Promise<DaemonHandle>;
 
-/**
- * Machine-level project registry + machine-wide daemon discovery.
- *
- * This module owns two surfaces under `~/.neat/`:
- *
- *  1. The legacy project registry at `~/.neat/projects.json` (ADR-048). One
- *     file, per-user, machine-local, not synced. Under the project-daemon
- *     contract (ADR-096) it is no longer the coordination point — it is read
- *     once for migration and otherwise left to the additive writes the daemon
- *     and orchestrator still perform. The read-modify-write helpers below keep
- *     their atomic-write + exclusive-lock machinery for that legacy surface.
- *
- *  2. The machine-wide daemon discovery directory at `~/.neat/daemons/`
- *     (ADR-096 §6). One file per running daemon — `<project>.json` — each owned
- *     solely by the daemon that wrote it (on start) and removes it (on graceful
- *     stop). Discovery is **append-only and lock-free**: a reader scans the
- *     directory and reconciles liveness; it never acquires a shared lock, so it
- *     can never deadlock against a daemon (#506). Losing or rebuilding the
- *     directory costs discovery convenience, not correctness — each project's
- *     own `neat-out/daemon.json` stays authoritative.
- *
- * `neat ps` / `neat list` and the per-daemon `pause` / `resume` / `uninstall`
- * verbs read discovery, falling back to the legacy registry where no daemon
- * file is present yet (the migration window before every daemon self-describes).
- *
- * The legacy lock is a file we exclusively-create (`O_EXCL`), hold while we
- * mutate, and unlink on the way out. Crude but cross-platform; matches what
- * `proper-lockfile` does internally without pulling the dep in. It never sits
- * on the discovery path.
- */
-
-declare function registryPath(): string;
-declare function registryLockPath(): string;
-/**
- * Path normalisation per ADR-048 #7. Two `init` calls from different relative
- * paths to the same dir must collapse to one entry. `path.resolve` handles
- * relative-to-cwd; we pass it through `fs.realpath` when the dir exists so
- * symlinked paths land on the same canonical entry too.
- */
-declare function normalizeProjectPath(input: string): Promise<string>;
-/**
- * tmp + fsync + rename. The fsync on the data fd guarantees the bytes are on
- * disk before rename swaps the inode; rename itself is atomic on POSIX.
- *
- * Exported so the init flow and test harnesses can use the same helper.
- */
-declare function writeAtomically(target: string, contents: string): Promise<void>;
-/**
- * Read the registry from disk. Returns an empty registry if the file does
- * not exist yet — first run, never registered anything.
- *
- * Throws on parse / schema errors. The contract is single-source-of-truth;
- * a corrupt file is louder than a silent reset.
- */
-declare function readRegistry(): Promise<RegistryFile>;
-interface AddProjectOptions {
-    name: string;
-    path: string;
-    languages?: string[];
-    status?: RegistryStatus;
-}
-/**
- * Anything the registry refuses to do.
- *
- * The identity lives on the class, not in the message text. Every caller that
- * prints one already prefixes its own name — the CLI writes `neat: ` — so a
- * message carrying `neat registry:` came out as `neat: neat registry: …`
- * (#1240). A non-CLI caller that wants to know where an error came from reads
- * `err.name`, which is more reliable than a string prefix anyway.
- */
-declare class RegistryError extends Error {
-    constructor(message: string);
-}
-declare class ProjectNameCollisionError extends RegistryError {
-    readonly projectName: string;
-    constructor(name: string);
-}
-/**
- * Register a project, or update its `lastSeenAt` if the same path is already
- * registered under the same name (idempotent re-init).
- *
- * Hard error on name collision against a different path — ADR-046 #7. The
- * caller can recover by passing `--project <new-name>`.
- */
-declare function addProject(opts: AddProjectOptions): Promise<RegistryEntry>;
-declare function getProject(name: string): Promise<RegistryEntry | undefined>;
-declare function listProjects(): Promise<RegistryEntry[]>;
-declare function setStatus(name: string, status: RegistryStatus): Promise<RegistryEntry>;
-declare function touchLastSeen(name: string, at?: string): Promise<void>;
-/**
- * Remove the registry entry for `name`. Per ADR-048 #6: this only removes the
- * registry row. It does **not** touch `neat-out/`, `policy.json`, or any user
- * file in the project directory. SDK-install rollback is a separate flow
- * (`neat-rollback.patch`) that the caller opts in to.
- */
-declare function removeProject(name: string): Promise<RegistryEntry | undefined>;
-
-export { type BuildApiOptions, type BuildOtelGrpcReceiverOptions, type BuildOtelReceiverOptions, type CompatPair, type CompatibilityResult, type DaemonHandle, type DaemonOptions, type ExtractResult, type GraphDiff, type IngestContext, type MarkStaleOptions, type NeatGraph, type OtelGrpcReceiver, type OtlpTracesRequest, type ParsedSpan, type PersistedSnapshot, ProjectNameCollisionError, type ProjectSlot, type SpanHandler, type StalenessLoopOptions, addProject, buildApi, buildOtelReceiver, checkCompatibility, compatPairs, computeGraphDiff, confidenceForEdge, extractFromDirectory, getBlastRadius, getGraph, getProject, getRootCause, handleSpan, listProjects, loadGraphFromDisk, loadSnapshotForDiff, logSpanHandler, makeSpanHandler, markStaleEdges, normalizeProjectPath, parseOtlpRequest, readErrorEvents, readRegistry, readStaleEvents, registryLockPath, registryPath, removeProject, resetGraph, routeSpanToProject, saveGraphToDisk, setStatus, startDaemon, startOtelGrpcReceiver, startPersistLoop, startStalenessLoop, stitchTrace, thresholdForEdgeType, touchLastSeen, writeAtomically };
+export { type BuildApiOptions, type BuildOtelGrpcReceiverOptions, type BuildOtelReceiverOptions, type CompatPair, type CompatibilityResult, type DaemonHandle, type DaemonOptions, type ExtractResult, type GraphDiff, type IngestContext, type MarkStaleOptions, type NeatGraph, type OtelGrpcReceiver, type OtlpTracesRequest, type ParsedSpan, type PersistedSnapshot, type ProjectSlot, type SpanHandler, type StalenessLoopOptions, buildApi, buildOtelReceiver, checkCompatibility, compatPairs, computeGraphDiff, confidenceForEdge, extractFromDirectory, getBlastRadius, getGraph, getRootCause, handleSpan, loadGraphFromDisk, loadSnapshotForDiff, logSpanHandler, makeSpanHandler, markStaleEdges, parseOtlpRequest, readErrorEvents, readStaleEvents, resetGraph, routeSpanToProject, saveGraphToDisk, startDaemon, startOtelGrpcReceiver, startPersistLoop, startStalenessLoop, stitchTrace, thresholdForEdgeType };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { MultiDirectedGraph } from 'graphology';
-import { GraphNode, GraphEdge, EdgeEvidence, SpanAttributes, EdgeTypeValue, StaleEvent, ErrorEvent, BlastRadiusResult, RootCauseResult, RegistryEntry, RegistryStatus, RegistryFile } from '@neat.is/types';
+import { GraphNode, GraphEdge, EdgeEvidence, ErrorEvent, SpanAttributes, EdgeTypeValue, StaleEvent, BlastRadiusResult, RootCauseResult, RegistryEntry } from '@neat.is/types';
 export { StaleEvent } from '@neat.is/types';
 import { FastifyInstance } from 'fastify';
+export { ProjectNameCollisionError, addProject, getProject, listProjects, normalizeProjectPath, readRegistry, registryLockPath, registryPath, removeProject, setStatus, touchLastSeen, writeAtomically } from './registry.js';
 
 type NeatGraph = MultiDirectedGraph<GraphNode, GraphEdge>;
 declare function getGraph(project?: string): NeatGraph;
@@ -46,6 +47,7 @@ interface ExtractOptions {
     project?: string;
     errorsPath?: string;
     source?: string;
+    announce?: boolean;
 }
 declare function extractFromDirectory(graph: NeatGraph, scanPath: string, opts?: ExtractOptions): Promise<ExtractResult>;
 
@@ -150,6 +152,43 @@ interface RepoSyncRequestResult {
     lastPass?: RepoSyncPassSummary;
 }
 
+interface PrVerdictRequest {
+    owner: string;
+    name: string;
+    baseSha: string;
+    headSha: string;
+    /** `https://x-access-token:<token>@github.com/<owner>/<name>.git`. Used for the two clones, then gone. */
+    cloneUrl: string;
+    /** Repo-relative paths the PR changes, from the caller. Absent → the two trees are compared. */
+    changedFiles?: string[];
+    tone?: 'loud' | 'professional';
+}
+interface PrVerdictResult {
+    marker: string;
+    body: string;
+    base: {
+        sha: string;
+        nodes: number;
+        edges: number;
+    };
+    head: {
+        sha: string;
+        nodes: number;
+        edges: number;
+    };
+    changedFiles: number;
+    observedBreaks: number;
+    divergences: number;
+    durationMs: number;
+}
+interface PrVerdictContext {
+    /** The project's live graph. Read for OBSERVED; never written. */
+    liveGraph: NeatGraph;
+    /** The project's recorded incidents, for symbol-grain divergences — the same read `/graph/divergences` does. */
+    incidents?: ErrorEvent[];
+}
+type PrVerdictRunner = (req: PrVerdictRequest, ctx: PrVerdictContext) => Promise<PrVerdictResult>;
+
 /**
  * A connector implements exactly one method. Everything downstream of
  * `poll()` — resolving a static call site, minting the OBSERVED edge — is
@@ -315,6 +354,9 @@ interface BuildApiOptions {
     staleEventsPath?: string;
     searchIndex?: SearchIndex;
     authToken?: string;
+    incidentStreamToken?: string;
+    /** Set only after the hosted substrate restores the complete errors ledger before boot. */
+    incidentReplayDurable?: boolean;
     trustProxy?: boolean;
     publicRead?: boolean;
     otlpReceiver?: () => FastifyInstance | undefined;
@@ -332,6 +374,7 @@ interface BuildApiOptions {
     };
     connectorsHome?: string;
     repoSync?: (project: string) => (() => RepoSyncRequestResult) | undefined;
+    prVerdict?: PrVerdictRunner;
     runPoll?: typeof runConnectorPoll;
 }
 declare function buildApi(opts: BuildApiOptions): Promise<FastifyInstance>;
@@ -684,101 +727,4 @@ interface DaemonHandle {
 declare function routeSpanToProject(serviceName: string | undefined, projects: ReadonlyArray<RegistryEntry>): string;
 declare function startDaemon(opts?: DaemonOptions): Promise<DaemonHandle>;
 
-/**
- * Machine-level project registry + machine-wide daemon discovery.
- *
- * This module owns two surfaces under `~/.neat/`:
- *
- *  1. The legacy project registry at `~/.neat/projects.json` (ADR-048). One
- *     file, per-user, machine-local, not synced. Under the project-daemon
- *     contract (ADR-096) it is no longer the coordination point — it is read
- *     once for migration and otherwise left to the additive writes the daemon
- *     and orchestrator still perform. The read-modify-write helpers below keep
- *     their atomic-write + exclusive-lock machinery for that legacy surface.
- *
- *  2. The machine-wide daemon discovery directory at `~/.neat/daemons/`
- *     (ADR-096 §6). One file per running daemon — `<project>.json` — each owned
- *     solely by the daemon that wrote it (on start) and removes it (on graceful
- *     stop). Discovery is **append-only and lock-free**: a reader scans the
- *     directory and reconciles liveness; it never acquires a shared lock, so it
- *     can never deadlock against a daemon (#506). Losing or rebuilding the
- *     directory costs discovery convenience, not correctness — each project's
- *     own `neat-out/daemon.json` stays authoritative.
- *
- * `neat ps` / `neat list` and the per-daemon `pause` / `resume` / `uninstall`
- * verbs read discovery, falling back to the legacy registry where no daemon
- * file is present yet (the migration window before every daemon self-describes).
- *
- * The legacy lock is a file we exclusively-create (`O_EXCL`), hold while we
- * mutate, and unlink on the way out. Crude but cross-platform; matches what
- * `proper-lockfile` does internally without pulling the dep in. It never sits
- * on the discovery path.
- */
-
-declare function registryPath(): string;
-declare function registryLockPath(): string;
-/**
- * Path normalisation per ADR-048 #7. Two `init` calls from different relative
- * paths to the same dir must collapse to one entry. `path.resolve` handles
- * relative-to-cwd; we pass it through `fs.realpath` when the dir exists so
- * symlinked paths land on the same canonical entry too.
- */
-declare function normalizeProjectPath(input: string): Promise<string>;
-/**
- * tmp + fsync + rename. The fsync on the data fd guarantees the bytes are on
- * disk before rename swaps the inode; rename itself is atomic on POSIX.
- *
- * Exported so the init flow and test harnesses can use the same helper.
- */
-declare function writeAtomically(target: string, contents: string): Promise<void>;
-/**
- * Read the registry from disk. Returns an empty registry if the file does
- * not exist yet — first run, never registered anything.
- *
- * Throws on parse / schema errors. The contract is single-source-of-truth;
- * a corrupt file is louder than a silent reset.
- */
-declare function readRegistry(): Promise<RegistryFile>;
-interface AddProjectOptions {
-    name: string;
-    path: string;
-    languages?: string[];
-    status?: RegistryStatus;
-}
-/**
- * Anything the registry refuses to do.
- *
- * The identity lives on the class, not in the message text. Every caller that
- * prints one already prefixes its own name — the CLI writes `neat: ` — so a
- * message carrying `neat registry:` came out as `neat: neat registry: …`
- * (#1240). A non-CLI caller that wants to know where an error came from reads
- * `err.name`, which is more reliable than a string prefix anyway.
- */
-declare class RegistryError extends Error {
-    constructor(message: string);
-}
-declare class ProjectNameCollisionError extends RegistryError {
-    readonly projectName: string;
-    constructor(name: string);
-}
-/**
- * Register a project, or update its `lastSeenAt` if the same path is already
- * registered under the same name (idempotent re-init).
- *
- * Hard error on name collision against a different path — ADR-046 #7. The
- * caller can recover by passing `--project <new-name>`.
- */
-declare function addProject(opts: AddProjectOptions): Promise<RegistryEntry>;
-declare function getProject(name: string): Promise<RegistryEntry | undefined>;
-declare function listProjects(): Promise<RegistryEntry[]>;
-declare function setStatus(name: string, status: RegistryStatus): Promise<RegistryEntry>;
-declare function touchLastSeen(name: string, at?: string): Promise<void>;
-/**
- * Remove the registry entry for `name`. Per ADR-048 #6: this only removes the
- * registry row. It does **not** touch `neat-out/`, `policy.json`, or any user
- * file in the project directory. SDK-install rollback is a separate flow
- * (`neat-rollback.patch`) that the caller opts in to.
- */
-declare function removeProject(name: string): Promise<RegistryEntry | undefined>;
-
-export { type BuildApiOptions, type BuildOtelGrpcReceiverOptions, type BuildOtelReceiverOptions, type CompatPair, type CompatibilityResult, type DaemonHandle, type DaemonOptions, type ExtractResult, type GraphDiff, type IngestContext, type MarkStaleOptions, type NeatGraph, type OtelGrpcReceiver, type OtlpTracesRequest, type ParsedSpan, type PersistedSnapshot, ProjectNameCollisionError, type ProjectSlot, type SpanHandler, type StalenessLoopOptions, addProject, buildApi, buildOtelReceiver, checkCompatibility, compatPairs, computeGraphDiff, confidenceForEdge, extractFromDirectory, getBlastRadius, getGraph, getProject, getRootCause, handleSpan, listProjects, loadGraphFromDisk, loadSnapshotForDiff, logSpanHandler, makeSpanHandler, markStaleEdges, normalizeProjectPath, parseOtlpRequest, readErrorEvents, readRegistry, readStaleEvents, registryLockPath, registryPath, removeProject, resetGraph, routeSpanToProject, saveGraphToDisk, setStatus, startDaemon, startOtelGrpcReceiver, startPersistLoop, startStalenessLoop, stitchTrace, thresholdForEdgeType, touchLastSeen, writeAtomically };
+export { type BuildApiOptions, type BuildOtelGrpcReceiverOptions, type BuildOtelReceiverOptions, type CompatPair, type CompatibilityResult, type DaemonHandle, type DaemonOptions, type ExtractResult, type GraphDiff, type IngestContext, type MarkStaleOptions, type NeatGraph, type OtelGrpcReceiver, type OtlpTracesRequest, type ParsedSpan, type PersistedSnapshot, type ProjectSlot, type SpanHandler, type StalenessLoopOptions, buildApi, buildOtelReceiver, checkCompatibility, compatPairs, computeGraphDiff, confidenceForEdge, extractFromDirectory, getBlastRadius, getGraph, getRootCause, handleSpan, loadGraphFromDisk, loadSnapshotForDiff, logSpanHandler, makeSpanHandler, markStaleEdges, parseOtlpRequest, readErrorEvents, readStaleEvents, resetGraph, routeSpanToProject, saveGraphToDisk, startDaemon, startOtelGrpcReceiver, startPersistLoop, startStalenessLoop, stitchTrace, thresholdForEdgeType };

package/dist/index.js

@@ -1,10 +1,8 @@
 import {
   routeSpanToProject,
   startDaemon
-} from "./chunk-Q2SL2SVH.js";
+} from "./chunk-EMFX3V77.js";
 import {
-  ProjectNameCollisionError,
-  addProject,
   buildApi,
   checkCompatibility,
   compatPairs,
@@ -13,39 +11,44 @@ import {
   extractFromDirectory,
   getBlastRadius,
   getGraph,
-  getProject,
   getRootCause,
   handleSpan,
-  listProjects,
   loadGraphFromDisk,
   loadSnapshotForDiff,
   makeSpanHandler,
   markStaleEdges,
-  normalizeProjectPath,
   readErrorEvents,
-  readRegistry,
   readStaleEvents,
-  registryLockPath,
-  registryPath,
-  removeProject,
   resetGraph,
   saveGraphToDisk,
-  setStatus,
   startPersistLoop,
   startStalenessLoop,
   stitchTrace,
-  thresholdForEdgeType,
+  thresholdForEdgeType
+} from "./chunk-6QMWJAWR.js";
+import {
+  ProjectNameCollisionError,
+  addProject,
+  getProject,
+  listProjects,
+  normalizeProjectPath,
+  readRegistry,
+  registryLockPath,
+  registryPath,
+  removeProject,
+  setStatus,
   touchLastSeen,
   writeAtomically
-} from "./chunk-DVCGDMTZ.js";
+} from "./chunk-RGYC5U2Q.js";
 import {
   startOtelGrpcReceiver
-} from "./chunk-LXQCL4MP.js";
+} from "./chunk-TZXSWSHX.js";
 import {
   buildOtelReceiver,
   logSpanHandler,
   parseOtlpRequest
-} from "./chunk-EFBWQIKG.js";
+} from "./chunk-QPG2QXCW.js";
+import "./chunk-MR64ICXX.js";
 export {
   ProjectNameCollisionError,
   addProject,