import type { ChunkingOptions } from "./chunking.js";
export type SqlParam = string | number | boolean | null | Uint8Array | Date | string[] | number[];
export interface QueryResult<T> {
    rows: T[];
    rowCount: number | null;
}
export interface SqlClient {
    query<T = Record<string, unknown>>(text: string, params?: SqlParam[]): Promise<QueryResult<T>>;
    transaction<T>(fn: (client: SqlClient) => Promise<T>): Promise<T>;
}
export declare class SqlError extends Error {
    readonly code: string;
    readonly detail?: string | undefined;
    readonly constraint?: string | undefined;
    readonly cause?: Error | undefined;
    constructor(message: string, code: string, detail?: string | undefined, constraint?: string | undefined, cause?: Error | undefined);
}
export declare class FsError extends Error {
    readonly code: string;
    readonly op: string;
    readonly path: string;
    constructor(code: string, op: string, path: string);
}
export declare class FsQuotaError extends FsError {
    readonly limit: number;
    readonly current: number;
    readonly attemptedDelta: number;
    constructor(op: string, path: string, limit: number, current: number, attemptedDelta: number);
}
export interface FsStat {
    isFile: boolean;
    isDirectory: boolean;
    isSymbolicLink: boolean;
    mode: number;
    size: number;
    mtime: Date;
}
export interface DirentEntry {
    name: string;
    isFile: boolean;
    isDirectory: boolean;
    isSymbolicLink: boolean;
}
export interface DirentStatEntry extends DirentEntry {
    mode: number;
    size: number;
    mtime: Date;
    symlinkTarget: string | null;
}
export interface WalkEntry extends DirentStatEntry {
    path: string;
    depth: number;
}
/** Options accepted by textSearch / semanticSearch / hybridSearch. */
export interface SearchOptions {
    path?: string;
    limit?: number;
    /** Max hits per file path (default 3) so one long page can't monopolize the top-k. */
    perFileCap?: number;
}
export interface MkdirOptions {
    recursive?: boolean;
    /** Initialize this directory as an independent version root. */
    versioned?: boolean;
}
export interface VersionedDirectoryOptions {
    version?: string;
}
export interface RmOptions {
    recursive?: boolean;
    /** Ignore a missing path. Does not delete version-root metadata. */
    force?: boolean;
    /** Permanently delete the version root mounted at this path. Requires recursive. */
    deleteVersionRoot?: boolean;
}
export interface CpOptions {
    recursive?: boolean;
}
export interface ReadFileRangeOptions {
    offset?: number;
    limit?: number;
}
export interface ReadFileLinesOptions {
    /** 1-indexed line number to start from. Default 1. */
    offset?: number;
    /** Maximum number of lines to return. Default: read to end. */
    limit?: number;
}
export interface ReadFileLinesResult {
    /** The requested slice of lines, joined by `\n`. No trailing newline. */
    content: string;
    /** Total number of lines in the file (excludes the empty element after a trailing newline). */
    total: number;
}
export interface SetupOptions {
    enableRLS?: boolean;
    enableFullTextSearch?: boolean;
    enableVectorSearch?: boolean;
    embeddingDimensions?: number;
    skipExtensions?: boolean;
}
export interface FsPermissions {
    read?: boolean;
    write?: boolean;
}
export type NodeType = "file" | "directory" | "symlink";
/** Public-facing shape of an entry at a single path in some version. */
export interface EntryShape {
    type: NodeType;
    mode: number;
    size: number;
    mtime: Date;
    /** Hex-encoded sha256 of the file's blob. `null` for directories and symlinks. */
    blobHash: string | null;
    /** Symlink target as stored. `null` for files and directories. */
    symlinkTarget: string | null;
}
export interface VersionDiffEntry {
    path: string;
    change: "added" | "removed" | "modified" | "type-changed";
    before: EntryShape | null;
    after: EntryShape | null;
    /**
     * File content on the parent side, populated only when the caller passes
     * `includeContent: true`. `null` for directories, symlinks, removed-side
     * absence, and files with no blob (empty). Binary blobs are decoded as
     * UTF-8 — callers needing raw bytes should fall back to `readFile`.
     */
    beforeContent?: string | null;
    /** File content on the version side. See `beforeContent`. */
    afterContent?: string | null;
}
export interface VersionDiffOptions {
    path?: string;
    /**
     * Populate `beforeContent` / `afterContent` on each entry by joining
     * `fs_blobs`. Off by default. Only meaningful for files; directories and
     * symlinks return `null` on the corresponding side.
     */
    includeContent?: boolean;
}
export interface VersionDiffStreamOptions extends VersionDiffOptions {
    batchSize?: number;
}
export interface VersionDiffCountOptions extends VersionDiffOptions {
    /** Count entries where either side has this node type. Omit to count all changed paths. */
    nodeType?: NodeType;
}
export interface VersionHistoryOptions extends VersionDiffOptions {
    /** Maximum number of versions to return from the current version backwards. */
    limit?: number;
    /** Cursor returned by a previous `listHistory()` page. */
    cursor?: string;
    /** Include the root version as additions from an empty tree. Default: true. */
    includeRoot?: boolean;
    /**
     * Per-version change detail. `false` (default): omit. `"paths"`: cheap
     * `{ path, change }` summary (path-level only; `before`/`after` are `null`).
     * `true`: full `VersionDiffEntry` with before/after shapes.
     */
    includeChanges?: boolean | "paths";
}
export interface VersionHistoryResult {
    entries: VersionHistoryEntry[];
    nextCursor: string | null;
}
export interface VersionHistoryEntry {
    versionId: number;
    version: string;
    parentVersionId: number | null;
    parentVersion: string | null;
    createdAt: Date;
    /** Set when the branch/ref label was deleted but history was retained. */
    deletedAt: Date | null;
    changes: VersionDiffEntry[];
}
export interface SweepHistoryResult {
    /** Active versions retained as self-contained snapshots. */
    keptVersions: number;
    /** Hidden/deleted versions physically removed. */
    removedVersions: number;
    removedEntries: number;
    removedBlobs: number;
}
export type MergeStrategy = "fail" | "ours" | "theirs";
export interface ConflictEntry {
    path: string;
    base: EntryShape | null;
    ours: EntryShape | null;
    theirs: EntryShape | null;
}
export interface MergeResult {
    applied: string[];
    conflicts: ConflictEntry[];
    skipped: string[];
}
export interface RenameVersionResult {
    label: string;
    displacedLabel?: string;
}
export interface PromoteResult {
    label: string;
    displacedLabel?: string;
    droppedPrevious: boolean;
}
export interface WorkspaceUsage {
    workspaceId: string;
    /** Version used for visible/logical counts. */
    version: string;
    /** User path used for visible/logical counts. */
    path: string;
    /** Sum of visible file and symlink sizes in this version. */
    logicalBytes: number;
    /** Deduplicated blob bytes referenced by visible files under `path`. */
    referencedBlobBytes: number;
    /** Deduplicated bytes stored in fs_blobs for the whole workspace. */
    storedBlobBytes: number;
    /** Number of blobs stored for the whole workspace. */
    blobCount: number;
    /** Number of version labels in the active version root. */
    versions: number;
    /** Total fs_entries rows across the active version root, including tombstones. */
    entryRows: number;
    /** Tombstone rows across the active version root. */
    tombstoneRows: number;
    /** Visible non-tombstone nodes in this version, including root. */
    visibleNodes: number;
    visibleFiles: number;
    visibleDirectories: number;
    visibleSymlinks: number;
    /** Deduplicated blob stats across every live version in the version root, under `path`. Present when `includeAcrossVersions` was set. */
    acrossVersions?: {
        referencedBlobBytes: number;
        referencedBlobCount: number;
    };
    limits: {
        maxFiles: number;
        maxFileSize: number;
        maxWorkspaceBytes?: number;
    };
}
export interface WorkspaceUsageOptions {
    /** Scope visible/logical counts to this user path and its descendants. */
    path?: string;
    /** Also compute deduplicated blob bytes/count across every live version in the version root. Returned on `acrossVersions`. */
    includeAcrossVersions?: boolean;
}
export interface MountSpec {
    /** Absolute path (in this instance's path space) to expose. */
    path: string;
    /** When true, the subtree is read-only: writes under it are denied. */
    readonly?: boolean;
}
export interface PgFileSystemOptions {
    db: SqlClient;
    workspaceId?: string;
    /** Select an active version by label. Mutually exclusive with `versionId`. */
    version?: string;
    /**
     * Open one exact version by its immutable id, including retained history whose
     * label has been deleted. Mutually exclusive with `version` and requires
     * `permissions.write` to be false.
     */
    versionId?: number;
    /** Internal: version root path. Defaults to workspace root. */
    versionRoot?: string;
    /** Retain deleted version rows for git-like history, or physically discard them. Default: "discard". */
    historyRetention?: "retain" | "discard";
    permissions?: FsPermissions;
    rootDir?: string;
    /**
     * Gitignore-like patterns whose paths are hidden from this instance. Excluded
     * paths return `ENOENT` on read and write. Compiled once per instance and
     * pushed down as `WHERE NOT (...)` on every read query.
     *
     * Supported syntax (subset of gitignore): `name`, `name/`, `/name`, `*.ext`,
     * `dir/*.tmp`, `**\/foo`. Negation (`!pat`) and dir-only enforcement on
     * trailing slashes are not implemented.
     */
    exclude?: string[];
    /**
     * Restrict this instance to a set of mounted subtrees of the workspace. Only
     * paths inside a mount — plus the ancestor directories that lead down to them
     * — are visible; everything else reads as `ENOENT` (not "permission denied":
     * it simply isn't there). Writes are allowed only inside a non-readonly
     * mount. This is the single-workspace, scoped-per-view primitive: one version
     * graph, many restricted windows onto it.
     *
     * Omit (or pass `[]`) for an unrestricted view. A mount at `/` is treated as
     * no restriction.
     */
    mount?: MountSpec[];
    /** Maximum size of a single file write, in bytes. Default: 10 MiB. */
    maxFileSize?: number;
    /** If set, `readFile` rejects files larger than this many bytes. Default: unlimited. */
    maxReadSize?: number;
    /** Maximum number of entries (files + directories) per workspace. Default: 10000. */
    maxFiles?: number;
    /** Maximum deduplicated blob bytes per workspace. Default: unlimited. */
    maxWorkspaceBytes?: number;
    /** Maximum path depth (number of `/`-separated segments). Default: 50. */
    maxDepth?: number;
    /** Maximum levels of symlink indirection before ELOOP. Default: 16. */
    maxSymlinkDepth?: number;
    /** Maximum number of nodes a single `cp -r` may traverse. Default: 10000. */
    maxCpNodes?: number;
    statementTimeoutMs?: number;
    /**
     * The embedder: receives a batch of texts, returns one vector per text,
     * in order. Every embedding flows through it — the chunk-index pass
     * (`indexChunkEmbeddings()`, batches of 64) and query embeddings for
     * `semanticSearch`/`hybridSearch` (single-item batches). Never called by
     * the write path.
     */
    embed?: (texts: string[]) => Promise<number[][]>;
    embeddingDimensions?: number;
    /**
     * Maintain the chunk-level search index (`fs_blob_chunks`): every text file
     * write also stores its markdown-aware section chunks, keyed by the blob
     * hash — rewriting unchanged content costs one existence probe, never a
     * re-chunk. Pass `true` for the defaults or a `ChunkingOptions` to tune the
     * token budget/estimator. Off by default. For content written before this
     * was enabled, run `backfillChunks()`.
     */
    chunking?: boolean | ChunkingOptions;
    /**
     * Observability hook: receives one `query` event per SQL statement sent to
     * Postgres and one `op` event per public filesystem call when it settles.
     * Queries are attributed to the innermost op that issued them, also when a
     * caller (e.g. a just-bash session) runs ops concurrently. Inherited by
     * forks, `versioned()` children and `transaction()` facades. Off by
     * default; when unset nothing is wrapped. The sink runs synchronously on
     * the query path, so keep it cheap and non-throwing.
     */
    trace?: (event: TraceEvent) => void;
}
/** The public filesystem call a traced query ran under. */
export interface TraceOpRef {
    /** Unique per traced call within the process. */
    id: number;
    /** Method name, e.g. `readFile`, `readdirWithFileTypes`, `fork`. */
    name: string;
}
/** One SQL statement as it was sent to Postgres. */
export interface TraceQueryEvent {
    type: "query";
    /** Exact text sent, including any injected `set_config` CTE. */
    sql: string;
    /** Number of bound parameters (values are not included). */
    paramCount: number;
    durationMs: number;
    /** Rows returned; 0 when the statement failed. */
    rows: number;
    /** True when the statement ran inside an explicit transaction. */
    transaction: boolean;
    /**
     * Innermost traced op that issued it; null for untraced callers. A
     * statement shared by coalesced calls carries the op that enqueued first.
     */
    op: TraceOpRef | null;
    error?: unknown;
}
/** One public filesystem call, emitted when it settles. */
export interface TraceOpEvent {
    type: "op";
    id: number;
    name: string;
    /** The call's string arguments (paths, labels); other arguments omitted. */
    args: string[];
    durationMs: number;
    /**
     * Statements issued while this op was innermost (nested ops excluded).
     * Concurrent `exists`/`stat`/`lstat`/`readFile` calls share one coalesced
     * statement: it counts toward the op that enqueued first and the others
     * report 0, so sum across ops to count round-trips.
     */
    queries: number;
    /** Summed duration of those statements; can exceed `durationMs` when
     *  the op runs queries concurrently. */
    sqlMs: number;
    /** Enclosing traced op, e.g. the `transaction` a facade call ran in. */
    parentId: number | null;
    error?: unknown;
}
export type TraceEvent = TraceQueryEvent | TraceOpEvent;
/** One stored row of the chunk-level search index, in document order. */
export interface BlobChunk {
    chunkIndex: number;
    /** 1-indexed inclusive line range against the file's content. */
    startLine: number;
    endLine: number;
    /** Breadcrumb of the enclosing headings ("Title > H2 > H3"), if any. */
    headingPath: string | null;
    /** The indexed text: breadcrumb prefix + the section body. */
    content: string;
}
/**
 * One chunk-level search hit: a section of a visible file, addressable as
 * `path:startLine-endLine` and hydratable via `readFileLines()`.
 */
export interface ChunkSearchResult {
    path: string;
    /** 1-indexed inclusive line range against the file's content. */
    startLine: number;
    endLine: number;
    /** Breadcrumb of the enclosing headings ("Title > H2 > H3"), if any. */
    headingPath: string | null;
    /** The indexed text: breadcrumb prefix + the section body. */
    content: string;
    rank: number;
}
/** What `backfillChunks()` did, at the handle's current version. */
export interface BackfillChunksResult {
    /** Visible text blobs that were missing chunks and got chunked. */
    blobs: number;
    /** Chunk rows written for them. */
    chunks: number;
}
/** What `indexChunkEmbeddings()` did, at the handle's current version.
 *  Counts are distinct chunk contents (by content hash), not chunk rows —
 *  duplicate sections share a vector. */
export interface IndexChunkEmbeddingsResult {
    /** Distinct chunk contents visible at the version. */
    chunks: number;
    /** Contents that already had a cached embedding — not re-embedded. */
    cacheHits: number;
    /** Contents newly embedded (and cached) by this pass. */
    embedded: number;
}
//# sourceMappingURL=types.d.ts.map