@rce-mcp/data-plane 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,633 @@
+import { Pool } from "pg";
+import { type Redis as RedisClient } from "ioredis";
+import type { SearchContextOutput } from "@rce-mcp/contracts";
+import { sqliteRuntimeDriverName } from "./sqlite-runtime.js";
+export { sqliteRuntimeDriverName } from "./sqlite-runtime.js";
+export type RuntimeMode = "cloud" | "local" | "hybrid";
+export type LocalSqliteRuntime = ReturnType<typeof sqliteRuntimeDriverName>;
+export declare const CLOUD_REQUIRED_ENV_VARS: readonly ["DATABASE_URL", "REDIS_URL", "S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY_ID", "S3_SECRET_ACCESS_KEY"];
+export interface RuntimeModeResolution {
+    requested_mode: RuntimeMode;
+    effective_mode: "cloud" | "local";
+    cloud_configured: boolean;
+    missing_cloud_vars: string[];
+}
+export declare function parseRuntimeMode(value: string | undefined): RuntimeMode;
+export declare function missingCloudRuntimeEnvVars(env: NodeJS.ProcessEnv): string[];
+export declare function isCloudRuntimeConfigured(env: NodeJS.ProcessEnv): boolean;
+export declare function resolveRuntimeMode(env: NodeJS.ProcessEnv): RuntimeModeResolution;
+export interface CandidateScoreWeights {
+    lexical_weight: number;
+    vector_weight: number;
+    path_match_boost: number;
+    recency_boost: number;
+    generated_penalty: number;
+}
+export interface WorkspaceRecord {
+    workspace_id: string;
+    tenant_id: string;
+    project_root_path: string;
+    name: string;
+}
+export interface ReadyIndexRecord {
+    index_id: string;
+    workspace_id: string;
+    tenant_id: string;
+    index_version: string;
+    status: "indexing" | "ready" | "failed";
+    created_at: string;
+    updated_at: string;
+}
+export interface IndexMetadataRecord {
+    embedding_provider: string;
+    embedding_model?: string;
+    embedding_dimensions: number;
+    embedding_version?: string;
+    chunking_strategy: "language_aware" | "sliding";
+    chunking_fallback_strategy: "sliding";
+    created_at: string;
+}
+export interface RankChunksInput {
+    tenant_id: string;
+    index_id: string;
+    query: string;
+    query_embedding: number[];
+    query_tokens: string[];
+    top_k: number;
+    candidate_weights?: CandidateScoreWeights;
+    filters?: {
+        language?: string;
+        path_prefix?: string;
+        glob?: string;
+    };
+}
+export interface RankedChunkCandidate {
+    chunk_id: string;
+    file_id: string;
+    path: string;
+    start_line: number;
+    end_line: number;
+    snippet: string;
+    language?: string;
+    generated?: boolean;
+    updated_at: string;
+    score: number;
+    lexical_score: number;
+    vector_score: number;
+    path_match: boolean;
+    recency_boosted: boolean;
+}
+export interface PersistedChunk {
+    chunk_id: string;
+    file_id: string;
+    path: string;
+    start_line: number;
+    end_line: number;
+    snippet: string;
+    language?: string;
+    generated?: boolean;
+    updated_at: string;
+    embedding: number[];
+}
+export interface PersistedFileRecord {
+    file_id: string;
+    repo_path: string;
+    content_hash: string;
+    language?: string;
+}
+export interface UpsertFileInput {
+    tenant_id: string;
+    index_id: string;
+    repo_path: string;
+    content_hash: string;
+    size_bytes: number;
+    language?: string;
+    warning_metadata?: Record<string, unknown>;
+    updated_at?: string;
+}
+export interface UpsertChunkInput {
+    start_line: number;
+    end_line: number;
+    snippet: string;
+    embedding: number[];
+    generated?: boolean;
+    updated_at?: string;
+}
+export interface IndexRepository {
+    migrate(): Promise<void>;
+    upsertWorkspace(input: WorkspaceRecord): Promise<void>;
+    resolveWorkspaceByProjectRoot(tenant_id: string, project_root_path: string): Promise<WorkspaceRecord | undefined>;
+    resolveWorkspaceByWorkspaceId(tenant_id: string, workspace_id: string): Promise<WorkspaceRecord | undefined>;
+    createIndexVersion(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_version: string;
+        status?: "indexing" | "ready" | "failed";
+    }): Promise<ReadyIndexRecord>;
+    markIndexStatus(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_id: string;
+        status: "indexing" | "ready" | "failed";
+    }): Promise<void>;
+    getIndexByVersion(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_version: string;
+    }): Promise<ReadyIndexRecord | undefined>;
+    resetIndexContent(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<void>;
+    getLatestReadyIndex(input: {
+        tenant_id: string;
+        workspace_id: string;
+    }): Promise<ReadyIndexRecord | undefined>;
+    getFilesByIndex(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<PersistedFileRecord[]>;
+    copyFileFromIndex(input: {
+        tenant_id: string;
+        source_index_id: string;
+        target_index_id: string;
+        repo_path: string;
+    }): Promise<void>;
+    upsertFile(input: UpsertFileInput): Promise<{
+        file_id: string;
+    }>;
+    replaceFileChunks(input: {
+        tenant_id: string;
+        file_id: string;
+        repo_path: string;
+        chunks: UpsertChunkInput[];
+    }): Promise<void>;
+    saveManifest(input: {
+        index_id: string;
+        object_key: string;
+        checksum: string;
+    }): Promise<void>;
+    saveIndexMetadata?(input: {
+        tenant_id: string;
+        index_id: string;
+        embedding_provider: string;
+        embedding_model?: string;
+        embedding_dimensions: number;
+        embedding_version?: string;
+        chunking_strategy: "language_aware" | "sliding";
+        chunking_fallback_strategy: "sliding";
+    }): Promise<void>;
+    getIndexMetadata?(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<IndexMetadataRecord | undefined>;
+    listChunksByIndex(input: {
+        tenant_id: string;
+        index_id: string;
+        filters?: {
+            language?: string;
+            path_prefix?: string;
+            glob?: string;
+        };
+    }): Promise<PersistedChunk[]>;
+    rankChunksByIndex?(input: RankChunksInput): Promise<RankedChunkCandidate[]>;
+}
+export declare class SqliteIndexRepository implements IndexRepository {
+    private readonly dbPath;
+    private readonly db;
+    constructor(dbPath: string);
+    close(): void;
+    migrate(): Promise<void>;
+    upsertWorkspace(input: WorkspaceRecord): Promise<void>;
+    resolveWorkspaceByProjectRoot(tenant_id: string, project_root_path: string): Promise<WorkspaceRecord | undefined>;
+    resolveWorkspaceByWorkspaceId(tenant_id: string, workspace_id: string): Promise<WorkspaceRecord | undefined>;
+    createIndexVersion(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_version: string;
+        status?: "indexing" | "ready" | "failed";
+    }): Promise<ReadyIndexRecord>;
+    markIndexStatus(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_id: string;
+        status: "indexing" | "ready" | "failed";
+    }): Promise<void>;
+    getIndexByVersion(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_version: string;
+    }): Promise<ReadyIndexRecord | undefined>;
+    resetIndexContent(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<void>;
+    getLatestReadyIndex(input: {
+        tenant_id: string;
+        workspace_id: string;
+    }): Promise<ReadyIndexRecord | undefined>;
+    getFilesByIndex(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<PersistedFileRecord[]>;
+    copyFileFromIndex(input: {
+        tenant_id: string;
+        source_index_id: string;
+        target_index_id: string;
+        repo_path: string;
+    }): Promise<void>;
+    upsertFile(input: UpsertFileInput): Promise<{
+        file_id: string;
+    }>;
+    replaceFileChunks(input: {
+        tenant_id: string;
+        file_id: string;
+        repo_path: string;
+        chunks: UpsertChunkInput[];
+    }): Promise<void>;
+    saveManifest(input: {
+        index_id: string;
+        object_key: string;
+        checksum: string;
+    }): Promise<void>;
+    saveIndexMetadata(input: {
+        tenant_id: string;
+        index_id: string;
+        embedding_provider: string;
+        embedding_model?: string;
+        embedding_dimensions: number;
+        embedding_version?: string;
+        chunking_strategy: "language_aware" | "sliding";
+        chunking_fallback_strategy: "sliding";
+    }): Promise<void>;
+    getIndexMetadata(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<IndexMetadataRecord | undefined>;
+    listChunksByIndex(input: {
+        tenant_id: string;
+        index_id: string;
+        filters?: {
+            language?: string;
+            path_prefix?: string;
+            glob?: string;
+        };
+    }): Promise<PersistedChunk[]>;
+    rankChunksByIndex(input: RankChunksInput): Promise<RankedChunkCandidate[]>;
+}
+export declare class PostgresIndexRepository implements IndexRepository {
+    private readonly pool;
+    private readonly options;
+    private embeddingStorage;
+    constructor(pool: Pool, options?: {
+        chunkEmbeddingDimensions?: number;
+        preferPgVector?: boolean;
+    });
+    migrate(): Promise<void>;
+    upsertWorkspace(input: WorkspaceRecord): Promise<void>;
+    resolveWorkspaceByProjectRoot(tenant_id: string, project_root_path: string): Promise<WorkspaceRecord | undefined>;
+    resolveWorkspaceByWorkspaceId(tenant_id: string, workspace_id: string): Promise<WorkspaceRecord | undefined>;
+    createIndexVersion(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_version: string;
+        status?: "indexing" | "ready" | "failed";
+    }): Promise<ReadyIndexRecord>;
+    markIndexStatus(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_id: string;
+        status: "indexing" | "ready" | "failed";
+    }): Promise<void>;
+    getIndexByVersion(input: {
+        tenant_id: string;
+        workspace_id: string;
+        index_version: string;
+    }): Promise<ReadyIndexRecord | undefined>;
+    resetIndexContent(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<void>;
+    getLatestReadyIndex(input: {
+        tenant_id: string;
+        workspace_id: string;
+    }): Promise<ReadyIndexRecord | undefined>;
+    getFilesByIndex(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<PersistedFileRecord[]>;
+    copyFileFromIndex(input: {
+        tenant_id: string;
+        source_index_id: string;
+        target_index_id: string;
+        repo_path: string;
+    }): Promise<void>;
+    upsertFile(input: UpsertFileInput): Promise<{
+        file_id: string;
+    }>;
+    replaceFileChunks(input: {
+        tenant_id: string;
+        file_id: string;
+        repo_path: string;
+        chunks: UpsertChunkInput[];
+    }): Promise<void>;
+    saveManifest(input: {
+        index_id: string;
+        object_key: string;
+        checksum: string;
+    }): Promise<void>;
+    saveIndexMetadata(input: {
+        tenant_id: string;
+        index_id: string;
+        embedding_provider: string;
+        embedding_model?: string;
+        embedding_dimensions: number;
+        embedding_version?: string;
+        chunking_strategy: "language_aware" | "sliding";
+        chunking_fallback_strategy: "sliding";
+    }): Promise<void>;
+    getIndexMetadata(input: {
+        tenant_id: string;
+        index_id: string;
+    }): Promise<IndexMetadataRecord | undefined>;
+    listChunksByIndex(input: {
+        tenant_id: string;
+        index_id: string;
+        filters?: {
+            language?: string;
+            path_prefix?: string;
+            glob?: string;
+        };
+    }): Promise<PersistedChunk[]>;
+    rankChunksByIndex(input: RankChunksInput): Promise<RankedChunkCandidate[]>;
+    private insertChunk;
+    private globToPostgresRegex;
+}
+export declare function createPostgresPool(databaseUrl: string): Pool;
+export interface QueryCache {
+    get(cacheKey: string): Promise<SearchContextOutput | undefined>;
+    set(cacheKey: string, value: SearchContextOutput, ttlSeconds?: number): Promise<void>;
+    invalidateWorkspace(workspace_id: string): Promise<void>;
+}
+export interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode: "EX", ttlSeconds: number): Promise<unknown>;
+    keys(pattern: string): Promise<string[]>;
+    del(...keys: string[]): Promise<number>;
+    rpush(key: string, ...values: string[]): Promise<number>;
+    lrem(key: string, count: number, value: string): Promise<number>;
+    brpoplpush(source: string, destination: string, timeout: number): Promise<string | null>;
+    lrange(key: string, start: number, stop: number): Promise<string[]>;
+    llen(key: string): Promise<number>;
+    connect?(): Promise<unknown>;
+    status?: string;
+}
+export declare class RedisQueryCache implements QueryCache {
+    private readonly redis;
+    private readonly keyPrefix;
+    constructor(redis: RedisLike, options?: {
+        keyPrefix?: string;
+    });
+    get(cacheKey: string): Promise<SearchContextOutput | undefined>;
+    set(cacheKey: string, value: SearchContextOutput, ttlSeconds?: number): Promise<void>;
+    invalidateWorkspace(workspace_id: string): Promise<void>;
+    private wrapKey;
+}
+export declare class InMemoryQueryCache implements QueryCache {
+    private readonly cache;
+    get(cacheKey: string): Promise<SearchContextOutput | undefined>;
+    set(cacheKey: string, value: SearchContextOutput, ttlSeconds?: number): Promise<void>;
+    invalidateWorkspace(workspace_id: string): Promise<void>;
+}
+export declare class SqliteQueryCache implements QueryCache {
+    private readonly dbPath;
+    private readonly db;
+    constructor(dbPath: string);
+    close(): void;
+    get(cacheKey: string): Promise<SearchContextOutput | undefined>;
+    set(cacheKey: string, value: SearchContextOutput, ttlSeconds?: number): Promise<void>;
+    invalidateWorkspace(workspace_id: string): Promise<void>;
+}
+export interface IndexJobPayload {
+    job_id: string;
+    tenant_id: string;
+    workspace_id: string;
+    index_version: string;
+    manifest_key: string;
+    attempts: number;
+    enqueued_at: string;
+    claimed_at?: string;
+}
+interface FailedIndexJobPayload extends IndexJobPayload {
+    failed_at: string;
+    last_error: string;
+}
+export interface UsageMeteringRecordInput {
+    tenant_id: string;
+    workspace_id?: string;
+    tool_name: string;
+    trace_id: string;
+    status: "success" | "error";
+    latency_ms: number;
+    result_count: number;
+    units: number;
+    created_at?: string;
+}
+export interface AuditEventInput {
+    tenant_id: string;
+    subject: string;
+    action: string;
+    resource: string;
+    status: "success" | "error" | "denied";
+    trace_id: string;
+    details?: Record<string, unknown>;
+    created_at?: string;
+}
+export interface UsageSummary {
+    tenant_id: string;
+    tool_name: string;
+    request_count: number;
+    error_count: number;
+    total_units: number;
+    p95_latency_ms: number;
+    last_seen_at?: string;
+}
+export interface AuditEventRecord {
+    event_id: string;
+    tenant_id: string;
+    subject: string;
+    action: string;
+    resource: string;
+    status: "success" | "error" | "denied";
+    trace_id: string;
+    details?: Record<string, unknown>;
+    created_at: string;
+}
+export interface UsageMeterStore {
+    migrate(): Promise<void>;
+    recordUsage(input: UsageMeteringRecordInput): Promise<void>;
+    recordAuditEvent(input: AuditEventInput): Promise<void>;
+    listUsageSummary(input?: {
+        tenant_id?: string;
+        from?: string;
+        to?: string;
+    }): Promise<UsageSummary[]>;
+    listAuditEvents(input?: {
+        tenant_id?: string;
+        limit?: number;
+    }): Promise<AuditEventRecord[]>;
+}
+export interface ClaimedIndexJob {
+    raw: string;
+    payload: IndexJobPayload;
+}
+export interface IndexJobQueue {
+    enqueue(job: Omit<IndexJobPayload, "job_id" | "attempts" | "enqueued_at"> & {
+        job_id?: string;
+    }): Promise<IndexJobPayload>;
+    claimNext(timeoutSeconds?: number): Promise<ClaimedIndexJob | undefined>;
+    ack(claimed: ClaimedIndexJob): Promise<void>;
+    retryOrDeadLetter(claimed: ClaimedIndexJob, errorMessage: string): Promise<void>;
+    reclaimOrphaned(maxClaimAgeSeconds?: number): Promise<number>;
+    deadLetterCount(): Promise<number>;
+    pendingCount(): Promise<number>;
+    processingCount(): Promise<number>;
+    listDeadLetters(): Promise<FailedIndexJobPayload[]>;
+}
+export declare class RedisIndexJobQueue implements IndexJobQueue {
+    private readonly redis;
+    private readonly pendingKey;
+    private readonly processingKey;
+    private readonly deadLetterKey;
+    private readonly maxAttempts;
+    private readonly leasePrefix;
+    private readonly claimLeaseSeconds;
+    private readonly reconnectRetries;
+    private readonly reconnectDelayMs;
+    constructor(redis: RedisLike, options?: {
+        keyPrefix?: string;
+        maxAttempts?: number;
+        claimLeaseSeconds?: number;
+        reconnectRetries?: number;
+        reconnectDelayMs?: number;
+    });
+    enqueue(job: Omit<IndexJobPayload, "job_id" | "attempts" | "enqueued_at"> & {
+        job_id?: string;
+    }): Promise<IndexJobPayload>;
+    claimNext(timeoutSeconds?: number): Promise<ClaimedIndexJob | undefined>;
+    ack(claimed: ClaimedIndexJob): Promise<void>;
+    retryOrDeadLetter(claimed: ClaimedIndexJob, errorMessage: string): Promise<void>;
+    reclaimOrphaned(maxClaimAgeSeconds?: number): Promise<number>;
+    deadLetterCount(): Promise<number>;
+    pendingCount(): Promise<number>;
+    processingCount(): Promise<number>;
+    listDeadLetters(): Promise<FailedIndexJobPayload[]>;
+    private runRedisOperation;
+    private isRecoverableRedisError;
+    private leaseKey;
+}
+export declare class InMemoryIndexJobQueue implements IndexJobQueue {
+    private readonly pending;
+    private readonly dead;
+    private readonly processing;
+    private readonly maxAttempts;
+    constructor(options?: {
+        maxAttempts?: number;
+    });
+    enqueue(job: Omit<IndexJobPayload, "job_id" | "attempts" | "enqueued_at"> & {
+        job_id?: string;
+    }): Promise<IndexJobPayload>;
+    claimNext(): Promise<ClaimedIndexJob | undefined>;
+    ack(claimed: ClaimedIndexJob): Promise<void>;
+    retryOrDeadLetter(claimed: ClaimedIndexJob, errorMessage: string): Promise<void>;
+    reclaimOrphaned(maxClaimAgeSeconds?: number): Promise<number>;
+    deadLetterCount(): Promise<number>;
+    pendingCount(): Promise<number>;
+    processingCount(): Promise<number>;
+    listDeadLetters(): Promise<FailedIndexJobPayload[]>;
+}
+export declare class SqliteIndexJobQueue implements IndexJobQueue {
+    private readonly dbPath;
+    private readonly db;
+    private readonly maxAttempts;
+    private readonly claimTtlSeconds;
+    constructor(dbPath: string, options?: {
+        maxAttempts?: number;
+        claimTtlSeconds?: number;
+    });
+    close(): void;
+    enqueue(job: Omit<IndexJobPayload, "job_id" | "attempts" | "enqueued_at"> & {
+        job_id?: string;
+    }): Promise<IndexJobPayload>;
+    claimNext(timeoutSeconds?: number): Promise<ClaimedIndexJob | undefined>;
+    ack(claimed: ClaimedIndexJob): Promise<void>;
+    retryOrDeadLetter(claimed: ClaimedIndexJob, errorMessage: string): Promise<void>;
+    reclaimOrphaned(maxClaimAgeSeconds?: number): Promise<number>;
+    deadLetterCount(): Promise<number>;
+    pendingCount(): Promise<number>;
+    processingCount(): Promise<number>;
+    listDeadLetters(): Promise<FailedIndexJobPayload[]>;
+    private claimNextImmediate;
+}
+export declare class InMemoryUsageMeterStore implements UsageMeterStore {
+    private readonly usage;
+    private readonly audit;
+    migrate(): Promise<void>;
+    recordUsage(input: UsageMeteringRecordInput): Promise<void>;
+    recordAuditEvent(input: AuditEventInput): Promise<void>;
+    listUsageSummary(input?: {
+        tenant_id?: string;
+        from?: string;
+        to?: string;
+    }): Promise<UsageSummary[]>;
+    listAuditEvents(input?: {
+        tenant_id?: string;
+        limit?: number;
+    }): Promise<AuditEventRecord[]>;
+}
+export declare class SqliteUsageMeterStore implements UsageMeterStore {
+    private readonly dbPath;
+    private readonly db;
+    constructor(dbPath: string);
+    close(): void;
+    migrate(): Promise<void>;
+    recordUsage(input: UsageMeteringRecordInput): Promise<void>;
+    recordAuditEvent(input: AuditEventInput): Promise<void>;
+    listUsageSummary(input?: {
+        tenant_id?: string;
+        from?: string;
+        to?: string;
+    }): Promise<UsageSummary[]>;
+    listAuditEvents(input?: {
+        tenant_id?: string;
+        limit?: number;
+    }): Promise<AuditEventRecord[]>;
+}
+export declare class PostgresUsageMeterStore implements UsageMeterStore {
+    private readonly pool;
+    constructor(pool: Pool);
+    migrate(): Promise<void>;
+    recordUsage(input: UsageMeteringRecordInput): Promise<void>;
+    recordAuditEvent(input: AuditEventInput): Promise<void>;
+    listUsageSummary(input?: {
+        tenant_id?: string;
+        from?: string;
+        to?: string;
+    }): Promise<UsageSummary[]>;
+    listAuditEvents(input?: {
+        tenant_id?: string;
+        limit?: number;
+    }): Promise<AuditEventRecord[]>;
+}
+export declare function createRedisClient(url: string): RedisClient;
+export declare function buildQueryCacheKey(input: {
+    workspace_id: string;
+    index_version: string;
+    query: string;
+    top_k: number;
+    filters?: {
+        language?: string;
+        path_prefix?: string;
+        glob?: string;
+    };
+}): string;