@ryanstark24/sfgraph-core 1.1.0

package/dist/storage/interfaces.d.ts

@@ -0,0 +1,101 @@
+import type { OrgId, QualifiedName, Sha256 } from "@ryanstark24/sfgraph-shared";
+import type Database from "better-sqlite3";
+import type { EdgeFact, NodeFact, Org, RelType, Snapshot } from "../domain/index.js";
+export type BetterSqlite3Database = Database.Database;
+export interface Migration {
+    version: number;
+    description: string;
+    up(db: BetterSqlite3Database): void;
+}
+export interface MergeResult {
+    inserted: number;
+    updated: number;
+    unchanged: number;
+}
+export type SnippetSourceFormat = "apex" | "js" | "html" | "xml" | "json" | "flow" | "soql";
+export interface SnippetRecord {
+    orgId: OrgId;
+    qualifiedName: QualifiedName;
+    sourceFormat: SnippetSourceFormat;
+    sourceText: string;
+    startLine?: number;
+    endLine?: number;
+    sourceHash: Sha256;
+    llmExplanation?: string;
+    explainedAt?: number;
+}
+export interface SnippetUpsertResult {
+    inserted: boolean;
+    updated: boolean;
+    unchanged: boolean;
+}
+export interface GraphStore {
+    init(): Promise<void>;
+    close(): Promise<void>;
+    upsertOrg(org: Org): void;
+    getOrg(id: OrgId): Org | null;
+    touchSync(orgId: OrgId, iso: string): void;
+    deleteNode(orgId: OrgId, qname: QualifiedName): void;
+    deleteEdgesFor(orgId: OrgId, qname: QualifiedName): void;
+    mergeNodes(facts: NodeFact[]): MergeResult;
+    mergeEdges(facts: EdgeFact[]): MergeResult;
+    getNode(orgId: OrgId, qname: QualifiedName): NodeFact | null;
+    listNodesByLabel(orgId: OrgId, label: string, limit?: number): NodeFact[];
+    listEdgesFrom(orgId: OrgId, src: QualifiedName, relType?: RelType): EdgeFact[];
+    listEdgesTo(orgId: OrgId, dst: QualifiedName, relType?: RelType): EdgeFact[];
+    listAllQnames(orgId: OrgId): QualifiedName[];
+    countNodes(orgId: OrgId): number;
+    countEdges(orgId: OrgId): number;
+    transaction<T>(fn: () => T): T;
+    upsertSnippet(rec: SnippetRecord): SnippetUpsertResult;
+    getSnippet(orgId: OrgId, qname: QualifiedName): SnippetRecord | null;
+    updateSnippetExplanation(orgId: OrgId, qname: QualifiedName, llmExplanation: string, explainedAt: number): boolean;
+    listSnippetsMissingExplanation(orgId: OrgId, limit?: number): SnippetRecord[];
+}
+export interface VectorUpsertResult {
+    inserted: boolean;
+    deduped: boolean;
+}
+export interface NodeSearchHit {
+    qname: QualifiedName;
+    label: string;
+    distance: number;
+}
+export interface BundleSearchHit {
+    bundleId: string;
+    distance: number;
+}
+export interface VectorStore {
+    init(): Promise<void>;
+    close(): Promise<void>;
+    upsertNodeVector(orgId: OrgId, qname: QualifiedName, label: string, vector: Float32Array, contentHash: Sha256): VectorUpsertResult;
+    upsertBundleVector(orgId: OrgId, bundleId: string, vector: Float32Array, contentHash: Sha256): VectorUpsertResult;
+    searchNodes(orgId: OrgId, query: Float32Array, k: number, opts?: {
+        label?: string;
+    }): NodeSearchHit[];
+    searchBundles(orgId: OrgId, query: Float32Array, k: number): BundleSearchHit[];
+    countNodeVectors(orgId: OrgId): number;
+}
+export interface NodeDiff {
+    added: NodeFact[];
+    removed: NodeFact[];
+    changed: Array<{
+        before: NodeFact;
+        after: NodeFact;
+    }>;
+}
+export interface EdgeDiff {
+    added: EdgeFact[];
+    removed: EdgeFact[];
+}
+export interface SnapshotStore {
+    init(): Promise<void>;
+    createSnapshot(orgId: OrgId, label: string, isAuto: boolean): Snapshot;
+    listSnapshots(orgId: OrgId): Snapshot[];
+    getSnapshot(id: string): Snapshot | null;
+    deleteSnapshot(id: string): void;
+    diffNodes(orgId: OrgId, fromId: string | "current", toId: string | "current"): NodeDiff;
+    diffEdges(orgId: OrgId, fromId: string | "current", toId: string | "current"): EdgeDiff;
+    prune(orgId: OrgId, retainDays: number): number;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/storage/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../src/storage/interfaces.ts"],"names":[],"mappings":"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"}

package/dist/storage/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interfaces.js.map

package/dist/storage/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/storage/interfaces.ts"],"names":[],"mappings":""}

package/dist/storage/sqlite/graph-store.d.ts

@@ -0,0 +1,62 @@
+import type { OrgId, QualifiedName } from "@ryanstark24/sfgraph-shared";
+import type { EdgeFact, NodeFact, Org, RelType } from "../../domain/index.js";
+import type { BetterSqlite3Database, GraphStore, MergeResult, SnippetRecord, SnippetUpsertResult } from "../interfaces.js";
+export interface SqliteGraphStoreOptions {
+    dbPath: string;
+    backupDir?: string;
+    retainBackups?: number;
+    db?: BetterSqlite3Database;
+}
+export declare class SqliteGraphStore implements GraphStore {
+    readonly db: BetterSqlite3Database;
+    private readonly ownsDb;
+    private readonly opts;
+    private nodeLabelCache;
+    private edgeRelCache;
+    private initialized;
+    private closed;
+    constructor(opts: SqliteGraphStoreOptions);
+    init(): Promise<void>;
+    /**
+     * Flush WAL to the main DB file with a PASSIVE checkpoint. Cheap (no
+     * locking against readers) and lets the auto-checkpoint mechanism stay
+     * ahead of write pressure. Callers should invoke this at major phase
+     * boundaries (between extractors, before long-running parses) so the
+     * WAL never grows beyond a few hundred pages.
+     *
+     * Returns true if checkpoint succeeded, false on any error (best-effort).
+     */
+    checkpoint(): boolean;
+    close(): Promise<void>;
+    private loadCaches;
+    private ensureNodeTable;
+    private ensureEdgeTable;
+    upsertOrg(org: Org): void;
+    getOrg(id: OrgId): Org | null;
+    touchSync(orgId: OrgId, iso: string): void;
+    deleteNode(orgId: OrgId, qname: QualifiedName): void;
+    deleteEdgesFor(orgId: OrgId, qname: QualifiedName): void;
+    mergeNodes(facts: NodeFact[]): MergeResult;
+    mergeEdges(facts: EdgeFact[]): MergeResult;
+    getNode(orgId: OrgId, qname: QualifiedName): NodeFact | null;
+    listNodesByLabel(orgId: OrgId, label: string, limit?: number): NodeFact[];
+    listEdgesFrom(orgId: OrgId, src: QualifiedName, relType?: RelType): EdgeFact[];
+    listEdgesTo(orgId: OrgId, dst: QualifiedName, relType?: RelType): EdgeFact[];
+    /**
+     * Return every qualified name persisted for `orgId` across all label tables.
+     * Used by full-sync deletion detection to compute the difference between
+     * what was previously known and what the current sync touched.
+     */
+    listAllQnames(orgId: OrgId): QualifiedName[];
+    countNodes(orgId: OrgId): number;
+    countEdges(orgId: OrgId): number;
+    transaction<T>(fn: () => T): T;
+    upsertSnippet(rec: SnippetRecord): SnippetUpsertResult;
+    getSnippet(orgId: OrgId, qname: QualifiedName): SnippetRecord | null;
+    updateSnippetExplanation(orgId: OrgId, qname: QualifiedName, llmExplanation: string, explainedAt: number): boolean;
+    listSnippetsMissingExplanation(orgId: OrgId, limit?: number): SnippetRecord[];
+    getNodeLabelTables(): Map<string, string>;
+    getEdgeRelTables(): Map<string, string>;
+    _explainReverseEdgeQuery(relType: RelType): string;
+}
+//# sourceMappingURL=graph-store.d.ts.map

package/dist/storage/sqlite/graph-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-store.d.ts","sourceRoot":"","sources":["../../../src/storage/sqlite/graph-store.ts"],"names":[],"mappings":"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"}