gitnexus 1.6.10-rc.2 → 1.6.10-rc.21

package/dist/core/lbug/lbug-adapter.d.ts

@@ -2,7 +2,7 @@ import lbug from '@ladybugdb/core';
 import { KnowledgeGraph } from '../graph/types.js';
 import { NodeTableName } from './schema.js';
 import type { PdgEmitManifest } from './pdg-emit-sink.js';
-import type { CachedEmbedding } from '../embeddings/types.js';
+import { type CachedEmbedding } from '../embeddings/types.js';
 import { type ExtensionEnsureOptions } from './extension-loader.js';
 /** Result of splitting the relationship CSV into per-label-pair files. */
 export interface RelCsvSplitResult {
@@ -83,6 +83,21 @@ pdgEmitManifest?: PdgEmitManifest) => Promise<{
     warnings: string[];
 }>;
 export declare const COPY_CSV_OPTS = "(HEADER=true, ESCAPE='\"', DELIM=',', QUOTE='\"', PARALLEL=false, auto_detect=false)";
+/**
+ * Fallback: insert relationships one-by-one if COPY fails.
+ *
+ * Exported for the quoted-id round-trip tests in
+ * `test/integration/lbug-core-adapter.test.ts` (the `DELETE_FILES_CHUNK_SIZE`
+ * exported-for-tests precedent); production callers stay in this module.
+ * Bails silently when the adapter singleton is closed.
+ *
+ * KNOWN PRE-EXISTING NARROWING (distinct from the `''` escaping bug, NOT
+ * fixed here): the row regex below matches CSV fields with `[^"]*`, so an id
+ * containing a double quote (CSV-escaped as `""`) never matches and the edge
+ * is skipped. Tracked as part of the quote-in-id divergence documented in
+ * `rel-pair-routing.ts`.
+ */
+export declare const fallbackRelationshipInserts: (validRelLines: string[], validTables: Set<string>, getNodeLabel: (id: string) => string) => Promise<void>;
 export declare const getCopyQuery: (table: NodeTableName, filePath: string) => string;
 /**
  * Insert a single node to LadybugDB
@@ -198,6 +213,76 @@ export declare const safeClose: () => Promise<void>;
  */
 export declare const closeLbugBeforeExit: () => Promise<void>;
 export declare const closeLbug: () => Promise<void>;
+/**
+ * Thrown by {@link wipeLbugDbFiles} when a data-bearing member of the
+ * LadybugDB file family is still present after the bounded
+ * remove-and-verify retries (#2409, tri-review 4669518496 P2-4), and by
+ * run-analyze's dirty-recovery block when the crashed run's sidecars can
+ * neither be parked nor removed (this shipping review, FIX 1 — same lock
+ * class, same remediation, and the CLI already renders this type).
+ *
+ * Classify by TYPE (`err instanceof LbugWipeError`) — the repo norm from
+ * #2385 — never by message text. The MESSAGE is nonetheless fully
+ * self-contained (headline + blocked paths + remediation) because
+ * `gitnexus serve` forwards only `err.message` over worker IPC
+ * (analyze-worker-core.ts), so the serve surface has nothing but this
+ * string to show the user. The holder framing deliberately covers the
+ * own-process case (FIX 2, finder A): the blocking handle is often a
+ * lingering one from THIS process's just-closed DB or a transient AV scan
+ * — not necessarily another process — so an immediate re-run often
+ * succeeds.
+ */
+export declare class LbugWipeError extends Error {
+    /** Paths still present (or unverifiable) after all retries. */
+    readonly survivors: readonly string[];
+    constructor(survivors: readonly string[], options?: {
+        headline?: string;
+    });
+}
+/**
+ * Remove the LadybugDB file family and VERIFY each member is really gone.
+ *
+ * Owns the canonical 4-file family list — `<lbugPath>`, `.wal`, `.shadow`,
+ * `.lock` — so run-analyze's two wipe sites (full rebuild + the #2409
+ * escalation valve) can never drift apart. `.shadow` is included because a
+ * checkpoint-in-flight crash leaves a shadow sidecar, and a stale shadow next
+ * to a freshly created DB file is replay poison on the next open (#2409).
+ *
+ * Verification contract (tri-review 4669518496 P2-4 — the old inline loops
+ * swallowed rm failures and let `initLbug` reopen a still-populated DB the
+ * run believed it wiped): after `fs.rm({ recursive, force })`, each path is
+ * probed and counts as GONE only when the probe rejects with **ENOENT**. A
+ * resolving probe, or a rejection in the EPERM/EBUSY/EACCES class (Windows
+ * delete-pending / handle-release lag — see HANDLE_RELEASE_LOCK_CODES in
+ * lbug-config.ts), or any other code means the path is not verifiably gone:
+ * it is retried on the shared handle-release budget
+ * (HANDLE_RELEASE_PROBE_ATTEMPTS × linear HANDLE_RELEASE_PROBE_DELAY_MS,
+ * lbug-config.ts — the previous private mirror constants were
+ * documentation-coupled copies) and then handled by CLASS (this shipping
+ * review, FIX 2):
+ *
+ *   - DATA-BEARING members (`<lbugPath>`, `.wal`, `.shadow`) — a survivor
+ *     means the reopen would resurrect rows this run believes wiped: throw
+ *     a typed {@link LbugWipeError}.
+ *   - `.lock` — contentless: `initLbug` recreates it, and a genuinely held
+ *     lock surfaces as initLbug's own lock-busy classification (a better
+ *     error than this one). A `.lock`-only survivor (an AV-held
+ *     delete-pending handle outlasting the budget previously failed a
+ *     perfectly sound rebuild) logs a warning and CONTINUES.
+ *
+ * Linux unlinked-but-open (name gone, holder keeps the old inode) probes
+ * ENOENT and is accepted by design — both production wipe sites run after a
+ * real `closeLbug()`.
+ *
+ * Deliberately OUT of this contract: `cleanupOldKuzuFiles`
+ * (repo-manager.ts) sweeps the LEGACY kuzu-era file family during storage
+ * migration — different family, best-effort by design; and
+ * `sweepStaleSidecars` (lbug-config.ts) is a test-fixture-gated open-retry
+ * fallback that must never delete production files. Neither wipes the live
+ * DB the run is about to recreate, so neither needs (or may share) the
+ * loud-failure contract here.
+ */
+export declare const wipeLbugDbFiles: (lbugPath: string) => Promise<void>;
 export declare const isLbugReady: () => boolean;
 /**
  * Delete all nodes (and their relationships) for a specific file from LadybugDB
@@ -208,6 +293,43 @@ export declare const isLbugReady: () => boolean;
 export declare const deleteNodesForFile: (filePath: string, dbPath?: string) => Promise<{
     deletedNodes: number;
 }>;
+/**
+ * Chunk size for {@link deleteNodesForFiles}. 200 paths keeps each
+ * statement ~13KB (well inside parser limits) while a ~700-file write set
+ * still collapses from ~13,000 statements to 124: 31 statements per chunk
+ * (1 CodeEmbedding join-delete + 30 filePath-bearing node tables — the
+ * 32-table NODE_TABLES roster minus Community/Process) × 4 chunks. The
+ * original "~40" claim under-counted the per-chunk statement fan-out
+ * (tri-review 4669518496 accuracy sweep).
+ */
+export declare const DELETE_FILES_CHUNK_SIZE = 200;
+/**
+ * Batched variant of {@link deleteNodesForFile} for the incremental
+ * writeback (#2409). One `DETACH DELETE … WHERE n.filePath IN […]` per
+ * node table per chunk of paths, instead of a count + delete per table
+ * per FILE. The per-file loop issued ~13,000 single-row write
+ * transactions on a ~700-file write set — a WAL-append storm that made
+ * the incremental path slower than a full rebuild and is the write
+ * pattern behind the native mid-writeback deaths reported in #2409.
+ *
+ * NO general error swallowing: a zero-match chunk is a no-op success by
+ * construction (every node table except Community/Process has a filePath
+ * column), so anything thrown here is a real engine failure the caller
+ * must see — silently skipping was exactly how #2409 hid its root cause.
+ * The single tolerated exception (FIX 4) is the missing-embedding-table
+ * binder error on the embedding join-delete: a DB created without
+ * EMBEDDING_SCHEMA cannot own embedding rows, so skipping that one
+ * statement is sound, while failing would brick every incremental run on
+ * such a DB until `--force`. Statement count per chunk is unchanged by the
+ * multi-label join: 1 embedding join-delete + 30 node-table deletes = 31
+ * (the rejected per-label fallback shape would have been 19 + 30 = 49).
+ * Singleton-connection only: the analyze writeback owns the write lock,
+ * and `queryAndDrain` routes through `withConnLock` for it (the WAL
+ * checkpoint driver is live during this).
+ */
+export declare const deleteNodesForFiles: (filePaths: readonly string[], options?: {
+    onChunk?: (filesDone: number, filesTotal: number) => void;
+}) => Promise<void>;
 export declare const getEmbeddingTableName: () => string;
 /**
  * Return the distinct repo-relative paths of files that import
@@ -225,6 +347,30 @@ export declare const getEmbeddingTableName: () => string;
  * exports.
  */
 export declare const queryImporters: (targetFilePath: string) => Promise<string[]>;
+/**
+ * Batched variant of {@link queryImporters} for the incremental importer
+ * BFS (#2409): distinct importers of ANY of the target paths, one query per
+ * chunk per BFS depth instead of one query per frontier FILE (a ~700-file
+ * frontier was ~700 sequential round-trips, each taking the connection lock
+ * against the live WAL checkpoint driver — ~5.6s of the writeback measured).
+ *
+ * Same contract as the singular form: reads the pre-pipeline DB state and
+ * swallows per-chunk query failures into a smaller result (correctness
+ * degrades on that branch — under-expansion means possibly-stale edges —
+ * but the DB stays writable and the writeback proceeds). Unlike the singular
+ * form the degradation is not silent (tri-review 4669518496 P2-5): every
+ * dropped chunk is logged and reported through `options.onChunkFailure`, so
+ * the orchestrator can count it into the #2410 crash diagnostics
+ * (`incrementalInProgress.droppedImporterChunks`).
+ */
+export declare const queryImportersBatch: (targetFilePaths: readonly string[], options?: {
+    /**
+     * Invoked once per chunk whose IMPORTS query failed and was dropped from
+     * the expansion. Observability only — the degrade-don't-fail contract is
+     * unchanged (the result just shrinks by the failed chunk's importers).
+     */
+    onChunkFailure?: (chunkIndex: number, chunkSize: number, err: unknown) => void;
+}) => Promise<string[]>;
 /**
  * Drop every Community and Process node (and their MEMBER_OF /
  * STEP_IN_PROCESS edges via DETACH DELETE). Used at the start of an