lmgrep 0.1.18 → 0.2.1

package/dist/domain/corpus/Vector.js

@@ -0,0 +1,96 @@
+/**
+ * An embedding as a value object: a chunk's meaning, or a query's, as a point
+ * in the model's vector space.
+ *
+ * Every operation returns a new Vector; none mutate. Raw `number[]` stays the
+ * wire format at the LanceDB and provider boundaries — this type is for the
+ * domain, where naming the operation matters more than avoiding an allocation.
+ *
+ * Keep it that way. Scoring a whole table happens inside LanceDB, natively;
+ * the operations here run over single queries and result pages, where the
+ * allocations are free.
+ */
+export class Vector {
+    values;
+    constructor(values) {
+        this.values = values;
+    }
+    static from(values) {
+        return new Vector(values instanceof Float32Array ? Array.from(values) : values);
+    }
+    /** Zero vector of the given width — the identity for {@link plus}. */
+    static zeros(dimensions) {
+        return new Vector(new Array(dimensions).fill(0));
+    }
+    static mean(vectors) {
+        if (vectors.length === 0) {
+            throw new Error("Cannot take the mean of zero vectors");
+        }
+        return Vector.sum(vectors).scaledBy(1 / vectors.length);
+    }
+    static sum(vectors) {
+        if (vectors.length === 0) {
+            throw new Error("Cannot sum zero vectors");
+        }
+        const out = new Array(vectors[0].values.length).fill(0);
+        for (const v of vectors) {
+            for (let i = 0; i < out.length; i++)
+                out[i] += v.values[i];
+        }
+        return new Vector(out);
+    }
+    get dimensions() {
+        return this.values.length;
+    }
+    /** A mutable copy, for the provider and LanceDB boundaries. */
+    toArray() {
+        return [...this.values];
+    }
+    componentAt(index) {
+        return this.values[index];
+    }
+    dot(other) {
+        let s = 0;
+        for (let i = 0; i < this.values.length; i++) {
+            s += this.values[i] * other.values[i];
+        }
+        return s;
+    }
+    plus(other) {
+        const out = new Array(this.values.length);
+        for (let i = 0; i < out.length; i++) {
+            out[i] = this.values[i] + other.values[i];
+        }
+        return new Vector(out);
+    }
+    minus(other) {
+        const out = new Array(this.values.length);
+        for (let i = 0; i < out.length; i++) {
+            out[i] = this.values[i] - other.values[i];
+        }
+        return new Vector(out);
+    }
+    scaledBy(factor) {
+        const out = new Array(this.values.length);
+        for (let i = 0; i < out.length; i++)
+            out[i] = this.values[i] * factor;
+        return new Vector(out);
+    }
+    /** Unit vector in the same direction. A zero vector is returned unchanged. */
+    normalized() {
+        let s = 0;
+        for (const v of this.values)
+            s += v * v;
+        const n = Math.sqrt(s) || 1;
+        return this.scaledBy(1 / n);
+    }
+    /**
+     * Cosine distance, valid only for unit vectors — callers normalize first.
+     * Kept as `1 - dot` rather than a general cosine so the clustering hot path
+     * does not re-derive magnitudes it already knows are 1.
+     */
+    cosineDistanceTo(other) {
+        return 1 - this.dot(other);
+    }
+}
+//# sourceMappingURL=Vector.js.map

package/dist/domain/corpus/Vector.js.map

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

package/dist/domain/ports/ChatModelPort.d.ts

@@ -0,0 +1,57 @@
+/** A search the model asked for during a research loop. */
+export interface SearchToolCall {
+    query: string;
+    filePrefix?: string;
+    type?: string[];
+    language?: string[];
+    limit?: number;
+}
+/**
+ * How a model run ended.
+ *
+ * `interrupted` is separated from `failed` on purpose: a step cap, a timeout,
+ * or an overflowed context all leave the evidence gathered so far intact and
+ * worth synthesizing from, whereas a failure means the model is unreachable.
+ */
+export type ChatOutcome = {
+    status: "completed";
+    text: string;
+    steps: number;
+} | {
+    status: "interrupted";
+    reason: "timeout" | "context-overflow";
+    steps: number;
+} | {
+    status: "failed";
+    error: unknown;
+    steps: number;
+};
+export interface ToolLoopRequest {
+    system: string;
+    prompt: string;
+    maxSteps: number;
+    timeoutMs: number;
+    /** Describes the search tool to the model. */
+    toolDescription: string;
+    /** Runs a search the model requested, returning the text it should see. */
+    onSearch: (call: SearchToolCall) => Promise<string>;
+}
+export interface CompletionRequest {
+    system: string;
+    prompt: string;
+    timeoutMs: number;
+}
+/**
+ * A generative model that can drive a search tool.
+ *
+ * Deliberately narrow: research needs exactly one agentic loop and one
+ * single-shot completion, and keeping the port that small is what stops the
+ * provider SDK leaking into the use case.
+ */
+export interface ChatModelPort {
+    /** Whether a model is configured at all — `ask` is hidden when not. */
+    readonly isConfigured: boolean;
+    runToolLoop(request: ToolLoopRequest): Promise<ChatOutcome>;
+    /** One-shot completion; undefined when the model produced nothing. */
+    complete(request: CompletionRequest): Promise<string | undefined>;
+}

package/dist/domain/ports/ChatModelPort.js

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

package/dist/domain/ports/ChatModelPort.js.map

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

package/dist/domain/ports/ChunkRepositoryPort.d.ts

@@ -0,0 +1,42 @@
+import type { Chunk } from "../corpus/Chunk.js";
+import type { ContentHash } from "../corpus/ContentHash.js";
+import type { Vector } from "../corpus/Vector.js";
+import type { HitList } from "../retrieval/HitList.js";
+/** A chunk paired with the embedding to store alongside it. */
+export interface EmbeddedChunk {
+    chunk: Chunk;
+    vector: Vector;
+}
+/** The filters pushed down into the vector query rather than applied after. */
+export interface ChunkQuery {
+    vector: Vector;
+    limit: number;
+    /** Restrict to files under this repo-relative prefix. */
+    filePrefix?: string;
+    /** Restrict to these AST node types. */
+    types?: string[];
+    /**
+     * Whether to restrict results to the file versions the current branch
+     * references. Off for cross-project search, where the foreign database has
+     * no manifest for our branch.
+     */
+    scopeToBranch: boolean;
+}
+/** Text of one chunk, for vocabulary building. */
+export interface ChunkText {
+    name: string;
+    content: string;
+}
+/** Persistence for embedded chunks. */
+export interface ChunkRepositoryPort {
+    add(chunks: EmbeddedChunk[]): Promise<void>;
+    search(query: ChunkQuery): Promise<HitList>;
+    deleteByFiles(filePaths: string[]): Promise<void>;
+    /** Of the given chunk hashes, those already stored. */
+    existingHashes(hashes: ContentHash[]): Promise<Set<string>>;
+    count(): Promise<number>;
+    /** Chunk hashes grouped by file path, for status reporting. */
+    hashesByFile(): Promise<Map<string, string[]>>;
+    allHashes(): Promise<Set<string>>;
+    streamTexts(batchSize?: number): AsyncGenerator<ChunkText[]>;
+}

package/dist/domain/ports/ChunkRepositoryPort.js

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

package/dist/domain/ports/ChunkRepositoryPort.js.map

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

package/dist/domain/ports/ChunkerPort.d.ts

@@ -0,0 +1,5 @@
+import type { Chunk } from "../corpus/Chunk.js";
+/** Splits a source file into indexable chunks. */
+export interface ChunkerPort {
+    chunk(filePath: string, cwd: string): Promise<Chunk[]>;
+}

package/dist/domain/ports/ChunkerPort.js

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

package/dist/domain/ports/ChunkerPort.js.map

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

package/dist/domain/ports/DatabaseSessionPort.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The lifecycle of an open database connection.
+ *
+ * Closing matters: a LanceDB connection holds a native runtime and its decode
+ * buffers, so a CLI process that forgets to close one keeps that memory until
+ * it exits.
+ */
+export interface DatabaseSessionPort {
+    close(): void;
+}

package/dist/domain/ports/DatabaseSessionPort.js

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

package/dist/domain/ports/DatabaseSessionPort.js.map

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

package/dist/domain/ports/EmbedderPort.d.ts

@@ -0,0 +1,14 @@
+import type { Vector } from "../corpus/Vector.js";
+/**
+ * Turns text into embeddings.
+ *
+ * Documents and queries are separate operations because several models want
+ * different prefixes for each ("search_document: " vs "search_query: "), and
+ * getting that wrong degrades retrieval silently.
+ */
+export interface EmbedderPort {
+    /** Embed indexable documents, in provider-sized batches. */
+    embedDocuments(texts: string[]): Promise<Vector[]>;
+    /** Embed a single search query. */
+    embedQuery(query: string): Promise<Vector>;
+}

package/dist/domain/ports/EmbedderPort.js

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

package/dist/domain/ports/EmbedderPort.js.map

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

package/dist/domain/ports/FileManifestRepositoryPort.d.ts

@@ -0,0 +1,32 @@
+import type { ContentHash } from "../corpus/ContentHash.js";
+import type { FileManifest, SourceFile } from "../corpus/SourceFile.js";
+import type { Branch } from "../project/Branch.js";
+/** One manifest row: a file version recorded on a branch. */
+export interface ManifestEntry {
+    filePath: string;
+    fileHash: ContentHash;
+    branch: Branch;
+}
+/**
+ * The branch-scoped record of which file versions are indexed.
+ *
+ * Chunks are shared across branches by content; this is what decides which of
+ * them a branch can see.
+ */
+export interface FileManifestRepositoryPort {
+    /** Manifest for the repository's own branch. */
+    current(): Promise<FileManifest>;
+    /** Cached manifest used for scoping searches; see {@link invalidate}. */
+    branchVersions(): Promise<FileManifest | undefined>;
+    /** Drop the cached manifest after an index or import. */
+    invalidate(): void;
+    upsert(entries: SourceFile[]): Promise<void>;
+    deleteFiles(filePaths: string[]): Promise<void>;
+    /** Of the given file hashes, those any branch has already indexed. */
+    knownHashes(hashes: ContentHash[]): Promise<Set<string>>;
+    allEntries(): Promise<ManifestEntry[]>;
+    storedBranches(): Promise<string[]>;
+    deleteBranch(branch: string): Promise<void>;
+    /** Copy another branch's manifest onto ours; returns rows copied. */
+    copyFromBranch(sourceBranch: string): Promise<number>;
+}

package/dist/domain/ports/FileManifestRepositoryPort.js

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

package/dist/domain/ports/FileManifestRepositoryPort.js.map

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

package/dist/domain/ports/GitPort.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The git facts the domain needs. Narrow on purpose: project identity and
+ * branch topology only, so the domain never learns that git is a subprocess.
+ */
+export interface GitPort {
+    /** Absolute path of the working tree root, or undefined outside a repo. */
+    toplevel(cwd: string): string | undefined;
+    /**
+     * Absolute path of the repository directory shared by every worktree —
+     * the main checkout's `.git`, even when called from a linked worktree.
+     * This is what lets worktrees agree on one index without a registry.
+     */
+    commonDir(cwd: string): string | undefined;
+    /** Current branch name, or "HEAD" when detached. */
+    currentBranch(repoRoot: string): string | undefined;
+    /** URL of the `origin` remote, if one is configured. */
+    originUrl(repoRoot: string): string | undefined;
+    /** Merge base of `HEAD` and `ref`, if both are reachable. */
+    mergeBase(repoRoot: string, ref: string): string | undefined;
+    /** Number of commits `to` is ahead of `from`. */
+    commitDistance(repoRoot: string, from: string, to: string): number | undefined;
+    /** Local branch names. */
+    localBranches(repoRoot: string): string[];
+}

package/dist/domain/ports/GitPort.js

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

package/dist/domain/ports/GitPort.js.map

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

package/dist/domain/ports/IndexMaintenancePort.d.ts

@@ -0,0 +1,58 @@
+/** What a maintenance pass did to one table. */
+export interface TableOptimizeReport {
+    table: string;
+    rows: number;
+    /**
+     * `skipped-small` - below the ANN threshold, flat scan is fine.
+     * `needs-index`   - big enough to want an index, but training was not
+     *                   requested on this path. Searches stay on flat scan
+     *                   until `lmgrep index` or `lmgrep compact` runs.
+     * `created`       - trained a vector index for the first time.
+     * `optimized`     - compacted and absorbed the unindexed tail.
+     * `up-to-date`    - tail still within tolerance, nothing done.
+     * `dropped`       - a table no longer part of the schema was removed.
+     */
+    action: "skipped-small" | "needs-index" | "created" | "optimized" | "up-to-date" | "dropped";
+    unindexed?: number;
+}
+export interface OptimizeReport {
+    tables: TableOptimizeReport[];
+}
+export interface DedupeReport {
+    before: number;
+    after: number;
+    duplicateIds: number;
+    staleVersions: number;
+}
+export interface OptimizeOptions {
+    /** Ignore the unindexed-tail tolerance and optimize regardless. */
+    force?: boolean;
+    /**
+     * Permit training an index where none exists. Off by default: training
+     * reads every vector and peaks at several GB, which must not happen behind
+     * a background watcher.
+     */
+    create?: boolean;
+}
+/** Whether searches are answered by a vector index or a brute-force scan. */
+export interface VectorIndexState {
+    rows: number;
+    /** True when a vector index exists for the chunk table. */
+    built: boolean;
+    /** Rows appended since the index was last refreshed; these are scanned. */
+    unindexed: number;
+    /** False when the table is too small for an index to be worth training. */
+    worthBuilding: boolean;
+}
+/** Index upkeep: compaction, ANN index training, and duplicate removal. */
+export interface IndexMaintenancePort {
+    optimize(options?: OptimizeOptions): Promise<OptimizeReport>;
+    /** Full unconditional pass, including the non-vector tables. */
+    compact(): Promise<OptimizeReport>;
+    /** Drop duplicate and stale-version rows, rewriting the table. */
+    dedupe(): Promise<DedupeReport>;
+    /** Delete every table — a full rebuild from scratch. */
+    reset(): Promise<void>;
+    /** How searches are currently answered. */
+    vectorIndexState(): Promise<VectorIndexState>;
+}

package/dist/domain/ports/IndexMaintenancePort.js

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

package/dist/domain/ports/IndexMaintenancePort.js.map

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

package/dist/domain/ports/IndexMetadataPort.d.ts

@@ -0,0 +1,23 @@
+import type { IndexMetadata } from "../project/IndexMetadata.js";
+/**
+ * Reads and writes the metadata sidecar beside each database.
+ *
+ * Enumeration is deliberately not here: a database lives inside the repository
+ * it describes, so listing them is the registry's job, not the sidecar's.
+ */
+export interface IndexMetadataPort {
+    read(databasePath: string): IndexMetadata | undefined;
+    write(databasePath: string, metadata: Omit<IndexMetadata, "indexedAt">): void;
+    /** Whether a directory is an lmgrep database, or safely treatable as one. */
+    isDatabaseDirectory(databasePath: string): boolean;
+    /**
+     * Whether a directory actually holds an index.
+     *
+     * Deliberately stricter than {@link isDatabaseDirectory}, which answers a
+     * different question: that one guards destructive commands and so accepts
+     * an empty directory, since deleting one cannot lose data. Listing an
+     * empty directory as an index is the opposite mistake — it reports an
+     * index that is not there.
+     */
+    holdsIndex(databasePath: string): boolean;
+}

package/dist/domain/ports/IndexMetadataPort.js

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

package/dist/domain/ports/IndexMetadataPort.js.map

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

package/dist/domain/ports/LockPort.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The two locks guarding a database.
+ *
+ * They are separate because they answer different questions: the maintainer
+ * lock says "one process owns watching this index" and lives as long as that
+ * process, while the write mutex says "one writer at a time" and is held only
+ * around a build. Collapsing them would stop an ad-hoc index from ever running
+ * beside a watcher.
+ */
+export interface LockPort {
+    /** Claim long-lived ownership. False when another live process holds it. */
+    acquireMaintainer(): boolean;
+    releaseMaintainer(): void;
+    isMaintained(): boolean;
+    /** Run `work` holding the short-lived write mutex. */
+    withWriteLock<T>(work: () => Promise<T>): Promise<T>;
+}

package/dist/domain/ports/LockPort.js

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

package/dist/domain/ports/LockPort.js.map

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

package/dist/domain/ports/LoggerPort.d.ts

@@ -0,0 +1,5 @@
+/** Where progress and problems are reported. */
+export interface LoggerPort {
+    info(message: string): void;
+    error(message: string): void;
+}

package/dist/domain/ports/LoggerPort.js

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

package/dist/domain/ports/LoggerPort.js.map

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

package/dist/domain/ports/ProjectIndexesPort.d.ts

@@ -0,0 +1,20 @@
+/** One model's database for a project. */
+export interface ProjectIndex {
+    databasePath: string;
+    /** Full model string it was built with, when the sidecar records one. */
+    model?: string;
+    dimensions?: number;
+    indexedAt?: string;
+    bytes: number;
+}
+/**
+ * The databases a single project holds — one per embedding model.
+ *
+ * Read by direct observation rather than from bookkeeping: they are siblings
+ * in one directory, and looking is both cheaper and more truthful than a
+ * registry that can disagree with what is on disk.
+ */
+export interface ProjectIndexesPort {
+    /** Every database under a project's index home, largest first. */
+    list(indexHome: string): ProjectIndex[];
+}

package/dist/domain/ports/ProjectIndexesPort.js

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

package/dist/domain/ports/ProjectIndexesPort.js.map

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

package/dist/domain/ports/ProjectRegistryPort.d.ts

@@ -0,0 +1,42 @@
+/** A database this machine knows about, and where to find it. */
+export interface RegisteredIndex {
+    /** Working tree the index describes. */
+    root: string;
+    /**
+     * Set for a standalone index, named with `--in <name>`.
+     *
+     * Its `root` is only where it happened to be built from, so it is not a
+     * project: cross-project search resolves a project *path* to a database,
+     * and following that path would land on a different index entirely.
+     */
+    name?: string;
+    /** Origin remote, when the project has one. */
+    remote?: string;
+    /** Absolute path of the database directory. */
+    databasePath: string;
+    /** Full model string the index was built with. */
+    model?: string;
+    dimensions?: number;
+    /** When this entry was last written. */
+    indexedAt: string;
+}
+/**
+ * The list of indexes on this machine.
+ *
+ * Databases live inside the repositories they describe, which is what keeps
+ * them from being orphaned — but it also means nothing can enumerate them
+ * without walking the filesystem. This registry is that list: pointers only,
+ * a few hundred bytes each, and never the source of truth. An entry naming a
+ * database that no longer exists is a dangling pointer, not lost data, and is
+ * detected by looking rather than by bookkeeping.
+ */
+export interface ProjectRegistryPort {
+    /** Record (or refresh) the entry for a database. */
+    record(entry: Omit<RegisteredIndex, "indexedAt">): void;
+    /** Entries whose database still exists. */
+    list(): RegisteredIndex[];
+    /** Entries whose database is gone — safe to forget. */
+    dangling(): RegisteredIndex[];
+    /** Drop the entry for a database. */
+    forget(databasePath: string): void;
+}

package/dist/domain/ports/ProjectRegistryPort.js

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

package/dist/domain/ports/ProjectRegistryPort.js.map

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

package/dist/domain/ports/StateDirectoryPort.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Access to the machine-global directory lmgrep keeps beside its databases.
+ *
+ * Since databases moved inside the repositories they describe, what remains
+ * here is only what cannot live in a repository: coordination between
+ * processes on this machine, the pointer registry that makes indexes
+ * discoverable without scanning the filesystem, and databases for projects
+ * that have no repository to live in.
+ *
+ * Narrow by design: the domain needs to know where state lives, not how to
+ * read or write files.
+ */
+export interface StateDirectoryPort {
+    /** Absolute path of the state root (e.g. ~/.local/state/lmgrep). */
+    root(): string;
+    /** Whether `path` exists and is a directory. */
+    isDirectory(path: string): boolean;
+    /** Where lock files live. Machine-global: they coordinate processes. */
+    locksDirectory(): string;
+    /** Where registry entries live — one small JSON pointer per database. */
+    registryDirectory(): string;
+    /** Where databases live for projects outside any git repository. */
+    databasesDirectory(): string;
+    /**
+     * Databases written by versions that kept everything under the state root.
+     * Present only so they can be listed, adopted, or removed.
+     */
+    legacyDatabaseDirectories(): string[];
+}

package/dist/domain/ports/StateDirectoryPort.js

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

package/dist/domain/ports/StateDirectoryPort.js.map

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