autodev-cli 1.4.97 → 1.4.101

package/out/graphStore.d.ts

@@ -22,6 +22,14 @@
  *   3. Every `evaluation` identifies a `rubric`.
  *   4. Superseded nodes remain addressable — supersede never deletes; it links a
  *      new version with a `supersedes` edge and flags the old one.
+ *
+ * MATERIALISATION (Tier 0). The log is append-only, so reload is incremental: we
+ * remember a byte offset and apply only the newly-appended tail on top of the
+ * live maps (apply is idempotent last-writer-wins) — a full clear+rebuild only
+ * happens when the file shrank (a rewrite). Two derived indexes are kept in step:
+ * an adjacency index (nodeId → incident edges) and an entity canonical-key index
+ * (name → entity id) so `UsageService` / `usage-service` / `usage service` all
+ * resolve to ONE entity.
  */
 export type GraphNodeType = 'entity' | 'claim' | 'source' | 'artifact' | 'agent_run' | 'evaluation' | 'task' | 'commit' | 'metric' | 'note' | 'question' | 'decision';
 export type GraphEdgeType = 'mentions' | 'supports' | 'contradicts' | 'derived_from' | 'produced' | 'evaluates' | 'revises' | 'supersedes' | 'depends_on' | 'parent_of' | 'resolved_to' | 'relates_to';
@@ -32,6 +40,14 @@ export interface GraphNode {
     type: GraphNodeType;
     name: string;
     body?: string;
+    /**
+     * A one-line gist of the node — the navigation enabler (Tier 1, item 3).
+     * Agent-supplied at write (the writing agent already holds the context, and it
+     * rides its provenance like any write). Optional and purely additive: old log
+     * lines without `summary` replay fine. When absent on an interior/hub node, a
+     * deterministic structural rollup is synthesized on read (no LLM call).
+     */
+    summary?: string;
     props?: Record<string, unknown>;
     /** Where the fact came from (a citation, url, file:line, or a source node id). */
     source?: string;
@@ -69,6 +85,8 @@ export interface AddNodeInput {
     name: string;
     id?: string;
     body?: string;
+    /** One-line gist (Tier 1). Stamped with a `summaryAt` prop so staleness is detectable. */
+    summary?: string;
     props?: Record<string, unknown>;
     source?: string;
     inference?: boolean;
@@ -86,26 +104,227 @@ export interface AddEdgeInput {
 /** A write rejected by an invariant — the caller turns this into a helpful error. */
 export declare class GraphInvariantError extends Error {
 }
+/**
+ * Split a label into normalised word tokens: break camelCase / PascalCase and
+ * acronym boundaries into words, lowercase, and split on any non-alphanumeric.
+ * `"UsageService"` → `["usage","service"]`, `"usage-service"` → `["usage","service"]`,
+ * `"HTTPServer v2"` → `["http","server","v2"]`.
+ */
+export declare function tokenize(s: string): string[];
+/**
+ * Canonical dedup key for an entity name: a **sorted, de-duplicated token set**.
+ * This collapses camelCase, kebab-case and spaced spellings AND word order to a
+ * single key, so `UsageService`, `usage-service` and `usage service` map to one
+ * `entity:` id. Sorting means `"Service Usage"` also collapses onto the same key.
+ */
+export declare function canonicalKey(s: string): string;
+/** Rough token estimate for budgeting — ~4 chars/token. */
+export declare function estimateTokens(s: string): number;
+/**
+ * Parse a `file:line`-style source into its cumulative path segments — the spine
+ * an auto-scaffold builds (item 1). `"src/foo/bar.ts:12"` → `["src","src/foo",
+ * "src/foo/bar.ts"]`; `"pay.ts:10"` → `["pay.ts"]`. Returns null for a URL, a
+ * source-node id (`source:ab12`), or anything that doesn't look like a path — the
+ * scaffold is deterministic and conservative, never a guess.
+ */
+export declare function parseSourcePath(source: string | undefined): string[] | null;
+/** A scored query row (Tier 1) — reused by graph_query, graph_map and graph_search. */
+export interface ScoredNode {
+    node: GraphNode;
+    score: number;
+    textScore: number;
+    matched: string[];
+    substring: boolean;
+}
+/** One "where do I start" map entry: a node plus its effective (authored or synthesized) summary. */
+export interface MapEntry {
+    id: string;
+    type: GraphNodeType;
+    name: string;
+    summary?: string;
+    synthesized?: boolean;
+    stale?: boolean;
+    degree: number;
+}
+export interface GraphMap {
+    /** Pinned "core" tier (item 4): project invariants always prepended within budget. */
+    pinned: MapEntry[];
+    hubs: MapEntry[];
+    questions: MapEntry[];
+    decisions: MapEntry[];
+    contradictions: {
+        a: {
+            id: string;
+            name: string;
+        };
+        b: {
+            id: string;
+            name: string;
+        };
+    }[];
+}
+/** One node of a navigable table-of-contents (item 2). */
+export interface TocNode {
+    id: string;
+    type: string;
+    name: string;
+    summary?: string;
+    synthesized?: boolean;
+    /** Total parent_of children (before the maxChildren cap). */
+    childCount: number;
+    children: TocNode[];
+    /** Children collapsed by the maxChildren cap or depth bound — the "+K more". */
+    moreChildren?: number;
+}
+export interface TocResult {
+    roots: TocNode[];
+    /** True when the spine was sparse and roots fell back to deterministic clustering. */
+    clustered?: boolean;
+}
+/** One row of a graph_search bundle — citable, with the edge-path from its seed. */
+export interface SearchRow {
+    id: string;
+    type: GraphNodeType;
+    name: string;
+    score: number;
+    matched: string[];
+    summary?: string;
+    synthesized?: boolean;
+    inference?: boolean;
+    seedId: string;
+    /** The edge used to reach this node (undefined for a seed). */
+    via?: {
+        edge: GraphEdgeType;
+        fromId: string;
+        dir: 'out' | 'in';
+    };
+    /** Hop descriptors from the seed, e.g. ["supports→ claim:ab12"] — for explainability. */
+    path: string[];
+    conflicts: {
+        id: string;
+        name: string;
+    }[];
+}
+export interface SearchResult {
+    intent: string;
+    terms: string[];
+    budget: number;
+    hops: number;
+    rows: SearchRow[];
+}
 export declare class GraphStore {
     private identity;
     private readonly dir;
     private readonly file;
+    /** Disposable materialised cache for cold-start (item 3). JSONL stays the sole source of truth. */
+    private readonly snapshotFile;
+    private readonly snapshotEnabled;
+    /** Byte offset the on-disk snapshot covers (0 = none loaded/written this session). */
+    private snapshotCoversBytes;
+    /** Ops applied since the last snapshot was written/loaded — the regeneration trigger. */
+    private opsSinceSnapshot;
     private nodes;
     private edges;
+    /** nodeId → incident edges (both directions). Rebuilt on clear, kept in step in apply(). */
+    private adjacency;
+    /** entity canonical-key → entity node id — the dedup + legacy-id resolution index. */
+    private entityIndex;
     private lastSize;
     private lastMtimeMs;
-    constructor(workspaceRoot: string, identity: Identity);
+    /** byte offset up to (and including) the last COMPLETE log line we've applied. */
+    private lastOffset;
+    /** total log ops applied since the last full rebuild (for dead-weight telemetry). */
+    private appliedOps;
+    /** complete-but-corrupt (JSON-unparseable) MIDDLE lines seen; a torn FINAL line is NOT counted. */
+    private parseFailures;
+    /** wall-clock ms of the last (incremental or full) reload. */
+    private lastReplayMs;
+    /** Monotonic node-set version bumped by apply() — the invalidation signal reload uses. */
+    private mutationSeq;
+    /** IDF over the resident node set, memoised until mutationSeq changes (item 1). */
+    private idfCache;
+    private idfCacheSeq;
+    constructor(workspaceRoot: string, identity: Identity, opts?: {
+        snapshot?: boolean;
+    });
     /** Where the graph lives (for messages). */
     get path(): string;
     private ensureDir;
-    /** Re-materialise from disk when the log changed under us (another agent wrote). */
+    private clear;
+    /**
+     * Re-materialise from disk when the log changed under us (another agent wrote).
+     * INCREMENTAL: since the log is append-only we treat `lastOffset` as a byte
+     * cursor and apply only the newly-appended tail on top of the live maps (apply
+     * is idempotent). A full clear+rebuild happens only when the file shrank below
+     * our cursor (a rewrite). A torn final line is left unconsumed and picked up on
+     * a later tick once the writer finishes it. This is provably identical to a
+     * full replay because apply() is last-writer-wins and the log is append-only.
+     */
     reloadIfChanged(): void;
+    /**
+     * Cold-start load: if a valid snapshot covers a prefix of the current log, adopt
+     * it and tail-replay only the uncovered bytes; otherwise full-replay. The
+     * snapshot is a DISPOSABLE cache — a missing / stale / corrupt one simply falls
+     * back to full replay, and the JSONL is never touched.
+     */
+    private loadFromScratch;
+    /** sha256 of the first min(4096, covers) bytes of the log — the cheap rewrite guard. */
+    private headSig;
+    /**
+     * Adopt the on-disk snapshot iff it is a valid prefix of the current log:
+     * `coversBytes` in (0, size] AND the head-signature still matches (guards against
+     * a rewritten/truncated log whose prefix changed). Rebuilds the derived indexes
+     * from the resident node/edge set rather than trusting serialized indexes.
+     */
+    private tryLoadSnapshot;
+    /** Regenerate the snapshot when the uncovered tail grew past the byte/op threshold. */
+    private maybeWriteSnapshot;
+    /**
+     * Write the snapshot atomically (temp file + rename) so a partial write is never
+     * visible and concurrent multi-agent regenerations can't corrupt it — the loser
+     * of a rename race simply leaves a consistent, self-describing file behind. Snaps
+     * only the byte prefix we've fully applied (`lastOffset`), so a torn final line is
+     * never captured.
+     */
+    private writeSnapshot;
+    /** Force a snapshot now (test hook / explicit checkpoint). No-op when snapshots are disabled. */
+    materializeSnapshot(): boolean;
+    /** Read bytes [start,end), apply every COMPLETE line, and advance lastOffset past them. */
+    private replayRange;
     private apply;
+    private indexEntity;
+    private indexEdge;
+    private pushAdj;
+    private unindexEdge;
     private append;
     addNode(input: AddNodeInput): {
         node: GraphNode;
         created: boolean;
     };
+    /**
+     * The write path. `scaffold:true` (the public {@link addNode}) additionally runs
+     * the deterministic parent_of auto-scaffold (item 1); the scaffold's own entity
+     * writes pass `scaffold:false` so they never recurse.
+     */
+    private addNodeInternal;
+    /**
+     * Deterministically fill the parent_of tree from a fact's provenance — NO LLM.
+     * A `file:line` source on a claim/artifact/decision/note upserts `entity` nodes
+     * for the file and its ancestor dirs and links a `dir → file → fact` spine; a
+     * `props.area` tag upserts an area entity and parents the fact under it. Every
+     * derived node/edge carries this run's provenance and a `props.autoScaffold=true`
+     * marker, and is idempotent (deterministic ids + edge dedup) so re-adds and
+     * concurrent writers converge instead of duplicating.
+     */
+    private scaffold;
+    private scaffoldFromSource;
+    private scaffoldFromArea;
+    /** Is there already an edge of `type` from→to? (idempotency for scaffold/rollup edges). */
+    private hasEdge;
+    /** Add a parent_of edge (marked autoScaffold) unless it already exists. */
+    private linkParentOf;
+    /** Deterministic id for a new node: entities dedupe by canonical key (+ aliases), others are fresh. */
+    private mintId;
     addEdge(input: AddEdgeInput): GraphEdge;
     /**
      * Version a node: create the replacement, link it with a `supersedes` edge,
@@ -118,28 +337,172 @@ export declare class GraphStore {
         edge: GraphEdge;
     };
     getNode(idOrName: string): GraphNode | undefined;
+    /** Incident `contradicts` edges of a node, resolved to {id,name} of the other endpoint. */
+    contradictionsFor(id: string): {
+        id: string;
+        name: string;
+    }[];
+    /** Node degree (incident edge count) — shared ranking infra for Tier 1. */
+    degree(id: string): number;
+    /** IDF over the resident node set, memoised until the node set mutates. */
+    private idf;
+    /** Exponential recency lift in [0,1]: 1 at now, decaying with age (τ≈30d). */
+    private recencyDecay;
+    /** Field-weighted TF·IDF text score for a node against a set of query terms. */
+    private scoreNode;
+    /**
+     * Relevance-ranked query (Tier 1, item 1). OR-semantics: a node is a hit if it
+     * matches ≥1 query term OR contains the intent as an exact substring (the old
+     * behaviour, kept as a guaranteed-inclusion signal → strict superset). Ranked by
+     * `textScore·(1 + wRecency·decay + wDegree·log1p(degree))`. `mode:'recent'` keeps
+     * the pure recency order; superseded nodes hidden unless includeSuperseded.
+     */
+    scoredQuery(opts: {
+        type?: string;
+        text?: string;
+        id?: string;
+        includeSuperseded?: boolean;
+        limit?: number;
+        mode?: 'relevance' | 'recent';
+    }): ScoredNode[];
+    /**
+     * Search nodes by type and/or text. Thin wrapper over {@link scoredQuery}: with
+     * `text` it returns relevance-ranked hits (item 1); without, recency order. The
+     * old pure-substring behaviour survives as a guaranteed-inclusion subset.
+     */
     query(opts: {
         type?: string;
         text?: string;
         id?: string;
         includeSuperseded?: boolean;
         limit?: number;
+        mode?: 'relevance' | 'recent';
     }): GraphNode[];
     /**
      * Bounded neighbourhood around a node — the playbook's "context construction
      * from a graph": resolve the entity, expand a hop or two over allowed edge
      * types, and return a small, citable subgraph rather than the whole graph.
+     * Uses the adjacency index (O(visited degree), not O(E·hops)) and returns the
+     * BFS hop-distance per node so the caller can rank/token-budget the result.
+     * `includeConflicts` (default true) always follows `contradicts` edges so a
+     * conflicting claim can never be hidden by an `edgeTypes` filter.
      */
     neighbors(opts: {
         idOrName: string;
         hops?: number;
         edgeTypes?: string[];
         limit?: number;
+        includeConflicts?: boolean;
     }): {
         center: GraphNode;
         nodes: GraphNode[];
         edges: GraphEdge[];
+        dist: Record<string, number>;
     } | null;
+    /** Distinct neighbour nodes of a node (via the adjacency index). */
+    private neighborNodes;
+    /** `parent_of` children of a node (this node as the parent). */
+    private childrenOf;
+    /**
+     * DETERMINISTIC one-line rollup for an interior/hub node with NO authored
+     * summary — NO LLM call. Synthesised from structure: child (or, absent
+     * `parent_of` children, neighbour) type counts + the top child names by degree.
+     * Returns undefined for a leaf/low-degree node (nothing to summarise).
+     */
+    rollupSummary(id: string): string | undefined;
+    /**
+     * The summary to SHOW for a node: the authored one if present, else the
+     * deterministic structural rollup (flagged synthesized), else nothing.
+     */
+    effectiveSummary(node: GraphNode): {
+        text: string;
+        synthesized: boolean;
+    } | undefined;
+    /**
+     * An AUTHORED summary is stale when the node has been superseded, or gained a
+     * `parent_of` child AFTER the summary was written (`props.summaryAt`). Nodes
+     * with no authored summary are "unsummarized", not stale.
+     */
+    summaryStale(node: GraphNode): boolean;
+    private mapEntry;
+    /**
+     * "Where do I start" for an agent with no id/name in hand. Ranks entities (and
+     * any node when `focusType` unset) by degree() over the adjacency index, and
+     * bundles the open `question`s, freshest `decision`s, and live `contradicts`
+     * pairs it already knows how to find. Purely read-side; render via graphRender.
+     */
+    map(opts?: {
+        depth?: number;
+        focusType?: string;
+        maxChildren?: number;
+    }): GraphMap;
+    /** A node is pinned by `props.pinned===true` or by the reserved `props.area==='core'`. */
+    private isPinnedNode;
+    /** Live pinned nodes (project invariants) — always prepended within budget. */
+    pinnedNodes(): GraphNode[];
+    /** Set/clear the pin flag on a node (upsert; the node stays otherwise unchanged). */
+    pin(idOrName: string, pinned?: boolean): GraphNode;
+    /**
+     * Vectorless, explainable, CITABLE retrieval — the PageIndex centrepiece done
+     * without embeddings and without a server-side model (the calling agent is the
+     * reasoner). Seed with the item-1 ranked query on `intent`, then best-first
+     * expand a relevance-priority frontier: pop the best node, expand 1 hop
+     * (strong provenance edges — supports/derived_from/produced/evaluates/
+     * depends_on/parent_of — before weak relates_to/mentions), score newly-found
+     * nodes against the intent, push. Stop at node_budget. Each returned row cites
+     * `[id]` with the matched terms and the edge-path from its seed.
+     */
+    search(opts: {
+        intent: string;
+        nodeBudget?: number;
+        hops?: number;
+    }): SearchResult;
+    private parentOfChildIds;
+    private hasParentOfParent;
+    private hasParentOfChild;
+    /** Connected components of `pool` over the given (undirected) edge types. */
+    private components;
+    /**
+     * Depth-bounded, summarized hierarchy (PageIndex-style "text-stripped overview →
+     * drill"). The spine is `parent_of` (roots = entities with no incoming parent_of);
+     * where that spine is sparse the uncovered remainder falls back to deterministic
+     * clustering (by `props.area`, else connected components over relates_to/
+     * depends_on). Each level shows the top `maxChildren` by degree and collapses the
+     * rest to `+K more`. Summaries reuse {@link effectiveSummary}. Pass `root` to
+     * expand one branch.
+     */
+    toc(opts?: {
+        root?: string;
+        depth?: number;
+        focusType?: string;
+        maxChildren?: number;
+    }): TocResult;
+    /** Deterministic id for a cluster's rollup node, so concurrent rollups upsert not duplicate. */
+    private rollupId;
+    /** parent_of descendants of a node (transitive), excluding itself. */
+    private descendants;
+    private rollupFromMembers;
+    /** The rollup/summary node for a cluster centre, if one has been created. */
+    rollupNodeFor(idOrName: string): GraphNode | undefined;
+    /**
+     * Create or upsert a hierarchical rollup for a cluster (item 5). The cluster is a
+     * centre entity's `parent_of` descendants, or — absent a spine — its N-hop
+     * neighbourhood. The rollup is a `note` with `props.rollup=true` and a
+     * DETERMINISTIC id (`summary:<centre-key>`) so concurrent rollups of the same
+     * cluster upsert rather than duplicate; it links `derived_from → each member`
+     * (members stay fully addressable in `props.members`) and hangs under the centre
+     * via `parent_of` so it's discoverable in the TOC. Summary text is agent-supplied
+     * or the deterministic Tier-1 rollup (no LLM on the default path).
+     */
+    rollup(opts: {
+        idOrName?: string;
+        hops?: number;
+        summary?: string;
+    }): {
+        node: GraphNode;
+        members: string[];
+        created: boolean;
+    };
     stats(): {
         nodeCount: number;
         edgeCount: number;
@@ -149,5 +512,17 @@ export declare class GraphStore {
         isolated: number;
         contradictions: number;
         openQuestions: number;
+        unsummarized: number;
+        staleSummaries: number;
+        spinelessHubs: number;
+        pinned: number;
+        fileBytes: number;
+        totalOps: number;
+        deadWeight: number;
+        deadWeightRatio: number;
+        lastReplayMs: number;
+        estTokens: number;
+        parseFailures: number;
+        tornFinalLine: boolean;
     };
 }