@orquentra/codebuddy 0.0.0-stage → 2.4.1

package/dist/codebuddy-D2xJ6hFk.d.ts

@@ -0,0 +1,841 @@
+import { z } from 'zod';
+
+type ProviderCallType = "embedding" | "llm";
+type ProviderCallStatus = "success" | "failed" | "timeout" | "rate_limited" | "gated" | "fallback";
+type ProviderCallMetadata = {
+    model: string;
+    type: ProviderCallType;
+    status: ProviderCallStatus;
+    latencyMs: number;
+    tokens?: number;
+    error?: string;
+    retries: number;
+    fallbackTriggered: boolean;
+    coldStartWaitMs: number;
+    /** Wall-clock arrival stamp (ms epoch) set by repositories that keep call logs. */
+    recordedAt?: number;
+};
+type ProviderDiagnosticsHook = (metadata: ProviderCallMetadata) => void | Promise<void>;
+type EmbeddingRequest = {
+    input: string | string[];
+    model?: string;
+};
+type EmbeddingResponse = {
+    model: string;
+    /** Use an immutable revision when the provider supports one. */
+    revision?: string;
+    /** Version of pooling, normalization, and other preprocessing. */
+    schema?: string;
+    dimensions: number;
+    vectors: number[][];
+};
+type TextGenerationRequest = {
+    prompt: string;
+    model?: string;
+};
+type TextGenerationResponse = {
+    model: string;
+    text: string;
+};
+type ModelProvider = {
+    embed(request: EmbeddingRequest): Promise<EmbeddingResponse>;
+    generateText(request: TextGenerationRequest): Promise<TextGenerationResponse>;
+};
+
+type ProviderConfig = {
+    type: "huggingface";
+    apiKey?: string;
+};
+type WorkerConfig = {
+    pollIntervalMs?: number;
+    batchSize?: number;
+    maxAttempts?: number;
+};
+type CodeBuddyConfig = {
+    postgresUrl: string;
+    provider: ProviderConfig;
+    namespace: string;
+    projectRoot?: string;
+    tokenBudget?: number;
+    graphify?: {
+        enabled: boolean;
+        graphPath?: string | undefined;
+    };
+    worker?: WorkerConfig;
+};
+type CodeBuddyStatus = {
+    ready: boolean;
+    phase: "foundation" | "storage" | "runtime";
+    message: string;
+    namespaceId: string;
+};
+type MemoryWriteType = "interaction" | "fact" | "summary";
+type RememberInput = {
+    sessionId?: string;
+    content: string;
+    type?: MemoryWriteType;
+    idempotencyKey?: string;
+    agentId?: string;
+};
+type RememberBatchItem = RememberInput;
+type RememberResult = {
+    id: string;
+    sessionId: string;
+    deduplicated: boolean;
+};
+type RecallInput = {
+    sessionId: string;
+    query: string;
+    budget?: number;
+    callerModel?: string;
+    conflictMode?: "all" | "latest" | "highest_confidence";
+};
+type RecallResult = PlannedContext;
+type ShareInput = {
+    from: string;
+    to: string;
+    factIds: string[];
+    mode?: "reference" | "snapshot";
+    /** Snapshot mode: root of the target project whose Markdown store receives the copy. */
+    targetProjectRoot?: string;
+    agentId?: string;
+};
+type ShareResult = {
+    shared: number;
+};
+type UnshareInput = {
+    to: string;
+    factIds: string[];
+    agentId?: string;
+};
+type UnshareResult = {
+    revoked: number;
+};
+type ForgetResult = {
+    ok: boolean;
+    entityType: "interaction" | "fact" | "unknown";
+};
+type EmbeddingJobStatus = "pending" | "processing" | "ready" | "failed";
+type AuditAction = "remember" | "remember_batch" | "share" | "forget" | "config";
+
+type NamespaceRow = {
+    id: string;
+    name: string;
+};
+type InteractionInsert = {
+    id: string;
+    namespaceId: string;
+    sessionId: string;
+    content: string;
+    contentHash: string;
+    tokenCount: number;
+    createdByAgent?: string | undefined;
+};
+type FactInsert = {
+    id: string;
+    namespaceId: string;
+    content: string;
+    contentHash: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    /** Explicit single-valued proposition identity; null/absent allows multiple values. */
+    propositionKey?: string | null | undefined;
+    /** Imported provenance/lifecycle from the Markdown source; defaults apply when absent. */
+    confidence?: number | undefined;
+    createdAt?: Date | undefined;
+    sourceDeleted?: boolean | undefined;
+    supersededBy?: string | null | undefined;
+    sourceInteractionId?: string | undefined;
+    createdByAgent?: string | undefined;
+};
+type SummaryInsert = {
+    id: string;
+    namespaceId: string;
+    sessionId: string;
+    content: string;
+    version?: number | undefined;
+    tokenCount: number;
+    createdByAgent?: string | undefined;
+};
+/**
+ * A fact as declared by its Markdown file. Unlike {@link FactInsert} (which
+ * deduplicates `remember` writes by content), this upserts by stable ID and
+ * carries every field the file owns so import never resets lifecycle state.
+ */
+type FactFileUpsert = FactInsert & {
+    confidence: number;
+    sourceDeleted: boolean;
+    supersededBy: string | null;
+    createdAt: Date;
+};
+type SummaryFileUpsert = SummaryInsert & {
+    createdAt: Date;
+};
+/**
+ * `unchanged` writes nothing (replays are free); `updated` re-embeds only when
+ * the content changed.
+ */
+type FileUpsertResult = {
+    status: "inserted" | "updated" | "unchanged";
+};
+type PendingEmbeddingInsert = {
+    id: string;
+    namespaceId: string;
+    ownerType: MemoryWriteType;
+    ownerId: string;
+    embeddingModel: string;
+};
+type EmbeddingJob = {
+    id: string;
+    leaseToken: string;
+    leaseMs: number;
+    namespaceId: string;
+    ownerType: MemoryWriteType;
+    ownerId: string;
+    embeddingModel: string;
+    attempts: number;
+    content: string;
+};
+type WriteResult = {
+    id: string;
+    embeddingId: string;
+    sessionId: string;
+    deduplicated: boolean;
+};
+type AuditEntry = {
+    id: string;
+    namespaceId: string;
+    action: AuditAction;
+    entityType: string;
+    entityId?: string | undefined;
+    createdByAgent?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+};
+type ModelCallEntry = {
+    id: string;
+    namespaceId?: string | undefined;
+    metadata: ProviderCallMetadata;
+};
+type ShareWriteInput = {
+    id: string;
+    fromNamespaceId: string;
+    toNamespaceId: string;
+    sourceFactId: string;
+    mode: "reference" | "snapshot";
+    snapshotFactId?: string | undefined;
+    createdByAgent?: string | undefined;
+};
+type EmbeddingStatusSnapshot = {
+    id: string;
+    status: EmbeddingJobStatus;
+    attempts: number;
+    lastError: string | null;
+};
+type ReadyEmbedding = {
+    embeddingId: string;
+    ownerType: MemoryWriteType;
+    ownerId: string;
+    vector: number[];
+    embeddingModel: string;
+    embeddingSpace: string | null;
+};
+/** Bounded owner references; vectors stay inside the repository. */
+type SimilarEmbedding = Omit<ReadyEmbedding, "vector"> & {
+    score: number;
+};
+type SimilaritySearchInput = {
+    namespaceId: string;
+    /** Exact embedding space key (#37); vectors from another space never compare. */
+    embeddingSpace: string;
+    embeddingModel: string;
+    vector: number[];
+    limit: number;
+};
+type SimilaritySearchResult = {
+    method: "exact_pgvector" | "exact_memory";
+    candidates: SimilarEmbedding[];
+    compatibleReady: number;
+};
+type LexicalFactSearchResult = {
+    candidates: Array<RecentFact & {
+        score: number;
+    }>;
+    matchedFacts: number;
+};
+type RecentInteraction = {
+    id: string;
+    sessionId: string;
+    content: string;
+    tokenCount: number;
+    createdAt: Date;
+};
+type RecentFact = {
+    id: string;
+    content: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    propositionKey: string | null;
+    confidence: number;
+    sourceDeleted: boolean;
+    supersededBy: string | null;
+    createdByAgent: string | null;
+    createdAt: Date;
+};
+type RecentSummary = {
+    id: string;
+    sessionId: string;
+    content: string;
+    tokenCount: number;
+    createdAt: Date;
+};
+type PendingEmbeddingCounts = {
+    pending: number;
+    /** Claimed and inside their lease window. */
+    processing: number;
+    failed: number;
+    ready: number;
+};
+type ListedFact = {
+    id: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    content: string;
+    confidence: number;
+    sourceInteractionId: string | null;
+    sourceDeleted: boolean;
+    supersededBy: string | null;
+    createdByAgent: string | null;
+    createdAt: Date;
+};
+type ListedSummary = {
+    id: string;
+    sessionId: string;
+    content: string;
+    version: number;
+    tokenCount: number;
+    createdByAgent: string | null;
+    createdAt: Date;
+};
+type FactCursor = {
+    createdAt: Date;
+    id: string;
+};
+type NamespaceSummary = {
+    name: string;
+    factCount: number;
+    lastActivity: Date | null;
+};
+type AgentWriteBreakdown = {
+    agentId: string | null;
+    writes: number;
+};
+type MemoryStats = {
+    namespaces: number;
+    interactions: number;
+    facts: number;
+    summaries: number;
+    embeddings: PendingEmbeddingCounts;
+    modelCalls: {
+        last60s: number;
+        lastHour: number;
+        last24h: number;
+        gatedFailures: number;
+    };
+};
+type VectorIndexHealth = {
+    vectorCount: number;
+    indexName: string | null;
+    indexDefinition: string | null;
+    needsTuning: boolean;
+};
+type MemoryRepository = {
+    ensureNamespace(name: string): Promise<NamespaceRow>;
+    getNamespaceByName(name: string): Promise<NamespaceRow | null>;
+    withSessionLock<T>(namespaceId: string, sessionId: string, fn: () => Promise<T>): Promise<T>;
+    writeInteraction(input: {
+        interaction: InteractionInsert;
+        embedding: PendingEmbeddingInsert;
+        audit: AuditEntry;
+    }): Promise<WriteResult>;
+    writeFact(input: {
+        fact: FactInsert;
+        embedding: PendingEmbeddingInsert;
+        audit: AuditEntry;
+    }): Promise<WriteResult>;
+    writeSummary(input: {
+        summary: SummaryInsert;
+        embedding: PendingEmbeddingInsert;
+        audit: AuditEntry;
+    }): Promise<WriteResult>;
+    /**
+     * Markdown import: insert or update the fact with this ID in `namespaceId`,
+     * marking it file-backed. Throws (without writing) when the ID belongs to
+     * another namespace or the content duplicates a different fact.
+     */
+    upsertFactFromFile(input: {
+        fact: FactFileUpsert;
+        embedding: PendingEmbeddingInsert;
+        audit: AuditEntry;
+    }): Promise<FileUpsertResult>;
+    upsertSummaryFromFile(input: {
+        summary: SummaryFileUpsert;
+        embedding: PendingEmbeddingInsert;
+        audit: AuditEntry;
+    }): Promise<FileUpsertResult>;
+    /** IDs of rows a reindex imported from Markdown (the only rows reconcile may delete). */
+    listFileBackedIds(namespaceId: string): Promise<{
+        facts: string[];
+        summaries: string[];
+    }>;
+    claimPendingEmbeddings(limit: number): Promise<EmbeddingJob[]>;
+    renewEmbeddingLease(id: string, leaseToken: string): Promise<boolean>;
+    markEmbeddingReady(id: string, leaseToken: string, vector: number[], model: string, space?: string): Promise<boolean>;
+    markEmbeddingFailed(id: string, leaseToken: string, error: string, attempts: number, options?: {
+        maxAttempts?: number;
+    }): Promise<boolean>;
+    getEmbeddingStatus(id: string): Promise<EmbeddingStatusSnapshot | null>;
+    /** Grant (or re-grant after revocation) a live reference. Idempotent per target+fact. */
+    shareReference(input: ShareWriteInput): Promise<void>;
+    /** Tombstone live reference shares; returns how many were revoked. */
+    revokeShares(fromNamespaceId: string, toNamespaceId: string, factIds: string[]): Promise<number>;
+    /**
+     * Copy a fact into the target namespace. Idempotent: an existing snapshot of
+     * the same source (or an identical copy already in the target) is reused.
+     */
+    shareSnapshot(input: {
+        share: ShareWriteInput;
+        snapshotFact: FactInsert;
+        embedding: PendingEmbeddingInsert;
+    }): Promise<{
+        snapshotFactId: string;
+    }>;
+    /**
+     * Delete an interaction and mark every fact derived from it `sourceDeleted`.
+     * Returns the marked fact ids so callers can persist the same lifecycle
+     * state to Markdown.
+     */
+    forgetInteraction(namespaceId: string, id: string, audit: AuditEntry): Promise<{
+        found: boolean;
+        sourceDeletedFactIds: string[];
+    }>;
+    forgetFact(namespaceId: string, id: string, audit: AuditEntry): Promise<{
+        found: boolean;
+    }>;
+    forgetSummary(namespaceId: string, id: string, audit: AuditEntry): Promise<{
+        found: boolean;
+    }>;
+    recordModelCall(entry: ModelCallEntry): Promise<void>;
+    recordAudit(entry: AuditEntry): Promise<void>;
+    /**
+     * Ready embeddings visible to the namespace: its own, plus facts shared to it
+     * through live (non-tombstoned) reference shares from the owning namespace.
+     */
+    getReadyEmbeddings(namespaceId: string, limit: number, space?: string): Promise<ReadyEmbedding[]>;
+    /** Rank every compatible visible vector (own + live shares) before applying the limit. */
+    searchSimilarEmbeddings(input: SimilaritySearchInput): Promise<SimilaritySearchResult>;
+    /** Search durable facts across every session, including pending/failed embeddings. */
+    searchFactsLexically(namespaceId: string, query: string, limit: number): Promise<LexicalFactSearchResult>;
+    getRecentInteractions(namespaceId: string, sessionId: string, limit: number): Promise<RecentInteraction[]>;
+    getRecentFacts(namespaceId: string, limit: number): Promise<RecentFact[]>;
+    getLatestSummary(namespaceId: string, sessionId: string): Promise<RecentSummary | null>;
+    getInteractionsByIds(namespaceId: string, ids: string[]): Promise<RecentInteraction[]>;
+    /** Facts visible to the namespace (own + live reference shares), by id. */
+    getFactsByIds(namespaceId: string, ids: string[]): Promise<RecentFact[]>;
+    getSummariesByIds(namespaceId: string, ids: string[]): Promise<RecentSummary[]>;
+    /** Fetch one fact with its full SPO fields, or null when missing. */
+    getFactById(namespaceId: string, id: string): Promise<ListedFact | null>;
+    countEmbeddingStatuses(namespaceId: string): Promise<PendingEmbeddingCounts>;
+    listFacts(input: {
+        namespaceId: string;
+        subject?: string;
+        limit: number;
+        cursor?: FactCursor;
+    }): Promise<ListedFact[]>;
+    listSummaries(input: {
+        namespaceId: string;
+        limit: number;
+    }): Promise<ListedSummary[]>;
+    listNamespaces(): Promise<NamespaceSummary[]>;
+    getAgentWriteBreakdown(namespaceId?: string): Promise<AgentWriteBreakdown[]>;
+    getStats(namespaceId?: string): Promise<MemoryStats>;
+    pruneBefore(cutoff: Date): Promise<{
+        interactions: number;
+        facts: number;
+        summaries: number;
+    }>;
+    getVectorIndexHealth(namespaceId?: string): Promise<VectorIndexHealth>;
+};
+
+/** Identity of the coordinate system, including provider preprocessing. */
+type EmbeddingSpace = {
+    model: string;
+    revision: string;
+    schema: string;
+    dimensions: number;
+};
+type QueryEmbedding = {
+    vector: number[];
+    space: EmbeddingSpace;
+};
+
+type ConflictMode = "all" | "latest" | "highest_confidence";
+type PlanInput = {
+    namespace: string;
+    namespaceId: string;
+    sessionId: string;
+    query: string;
+    budget: number;
+    callerModel?: string | undefined;
+    conflictMode: ConflictMode;
+    queryEmbedding: QueryEmbedding | null;
+    repository: MemoryRepository;
+};
+/** Structured provenance for a recalled fact; `conflict` is set when its proposition key had rivals. */
+type FactProvenance = {
+    id: string;
+    subject: string;
+    predicate: string;
+    object: string;
+    propositionKey: string | null;
+    confidence: number;
+    createdAt: string;
+    createdByAgent: string | null;
+    conflict?: {
+        /** All recalled candidates sharing the proposition key, sorted by id. */
+        candidateIds: string[];
+        /** True when rival objects remain that the conflict mode could not decide between. */
+        unresolved: boolean;
+    };
+};
+type PlannedMessage = {
+    role: "system" | "user" | "assistant";
+    content: string;
+    fact?: FactProvenance;
+};
+type SkipReason = "budget_exhausted" | "low_score" | "duplicate" | "superseded" | "source_deleted";
+type PlannerStats = {
+    /** cl100k tokens in system plus every message content; excludes transport framing. */
+    tokensUsed: number;
+    budgetStatus?: "within_budget" | "overflow";
+    budgetWarning?: string;
+    itemsIncluded: number;
+    itemsSkipped: number;
+    budgetHeadroom: number;
+    fallback: "none" | "recency" | "summary" | "recency_summary";
+    skipReasons: Partial<Record<SkipReason, number>>;
+    embeddingCoverage: {
+        ready: number;
+        pending: number;
+        failed: number;
+    };
+    /** Optional for custom policy compatibility; always supplied by DefaultPolicy. */
+    candidateCoverage?: {
+        scope: "full_namespace";
+        method: "exact_pgvector" | "exact_memory" | "lexical";
+        compatibleReady: number;
+        candidateLimit: number;
+        vectorCandidates: number;
+        lexicalCandidates: number;
+        lexicalMatchedFacts: number;
+        hydratedCandidates: number;
+        /** Embedding space key the vector search was restricted to (#37). */
+        spaceFilter: string | null;
+    };
+    fallbackReason?: "query_embedding_unavailable" | "invalid_query_vector" | "no_ready_embeddings" | "no_compatible_embeddings" | "no_hydratable_candidates";
+    explain?: string[];
+    budgetClamped: boolean;
+    budgetClampReason?: string;
+};
+type PlannedContext = {
+    system: string;
+    messages: PlannedMessage[];
+    stats: PlannerStats;
+};
+type ContextPolicy = {
+    plan(input: PlanInput): Promise<PlannedContext>;
+};
+
+type TraceMetadata = Record<string, unknown>;
+type TraceSpan = {
+    end(metadata?: TraceMetadata): void;
+    fail(error: unknown, metadata?: TraceMetadata): void;
+};
+type Tracer = {
+    enabled: boolean;
+    startSpan(name: string, input?: TraceMetadata): TraceSpan;
+    withSpan<T>(name: string, input: TraceMetadata, fn: () => Promise<T>): Promise<T>;
+};
+declare function isLangSmithTracingEnabled(env?: NodeJS.ProcessEnv): boolean;
+declare function createTracer(env?: NodeJS.ProcessEnv): Tracer;
+
+declare const codeBuddyConfigSchema: z.ZodObject<{
+    postgresUrl: z.ZodString;
+    provider: z.ZodObject<{
+        type: z.ZodLiteral<"huggingface">;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    namespace: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
+    tokenBudget: z.ZodOptional<z.ZodNumber>;
+    graphify: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        graphPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    worker: z.ZodOptional<z.ZodObject<{
+        pollIntervalMs: z.ZodOptional<z.ZodNumber>;
+        batchSize: z.ZodOptional<z.ZodNumber>;
+        maxAttempts: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ValidatedCodeBuddyConfig = z.infer<typeof codeBuddyConfigSchema>;
+
+declare const FACT_CATEGORIES: readonly ["general", "incident"];
+type FactCategory = (typeof FACT_CATEGORIES)[number];
+declare const INCIDENT_SEVERITIES: readonly ["low", "medium", "high", "critical"];
+type IncidentSeverity = (typeof INCIDENT_SEVERITIES)[number];
+declare const factFrontMatterSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    namespace: z.ZodString;
+    type: z.ZodLiteral<"fact">;
+    subject: z.ZodString;
+    predicate: z.ZodString;
+    object: z.ZodString;
+    propositionKey: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    confidence: z.ZodNumber;
+    createdAt: z.ZodPreprocess<z.ZodString, unknown>;
+    createdByAgent: z.ZodNullable<z.ZodString>;
+    sourceInteractionId: z.ZodNullable<z.ZodString>;
+    sourceDeleted: z.ZodBoolean;
+    category: z.ZodDefault<z.ZodEnum<{
+        incident: "incident";
+        general: "general";
+    }>>;
+    paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    severity: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        critical: "critical";
+    }>>>;
+    introducedBy: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    resolvedBy: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    fingerprint: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    sourcePlanId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    sourceSessionId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    verification: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    supersededBy: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    sharedWith: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+declare const summaryFrontMatterSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    namespace: z.ZodString;
+    type: z.ZodLiteral<"summary">;
+    sessionId: z.ZodString;
+    version: z.ZodNumber;
+    tokenCount: z.ZodNumber;
+    createdAt: z.ZodPreprocess<z.ZodString, unknown>;
+    createdByAgent: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type FactFile = z.infer<typeof factFrontMatterSchema> & {
+    content: string;
+    path: string;
+};
+type FactFileWrite = Omit<FactFile, "path" | "schemaVersion" | "type" | "category" | "paths" | "severity" | "introducedBy" | "resolvedBy" | "fingerprint" | "sourcePlanId" | "sourceSessionId" | "verification" | "supersededBy" | "sharedWith" | "propositionKey"> & Partial<Pick<FactFile, "category" | "paths" | "severity" | "introducedBy" | "resolvedBy" | "fingerprint" | "sourcePlanId" | "sourceSessionId" | "verification" | "supersededBy" | "sharedWith" | "propositionKey">>;
+type IncidentFactFile = FactFile & {
+    category: "incident";
+    severity: IncidentSeverity;
+};
+type SummaryFile = z.infer<typeof summaryFrontMatterSchema> & {
+    content: string;
+    path: string;
+};
+type SummaryFileWrite = Omit<SummaryFile, "path" | "schemaVersion" | "type">;
+/** A managed memory file that exists on disk but could not be parsed. */
+type InvalidMemoryFile = {
+    id: string;
+    path: string;
+    error: string;
+};
+declare class MemoryFileStore {
+    readonly repositoryRoot: string;
+    readonly factsDirectory: string;
+    readonly summariesDirectory: string;
+    constructor(repositoryRoot?: string);
+    writeFact(raw: FactFileWrite): Promise<string>;
+    writeSummary(input: SummaryFileWrite): Promise<string>;
+    readFact(pathOrId: string): Promise<FactFile>;
+    listFacts(): Promise<FactFile[]>;
+    /**
+     * Parse every managed fact file. Hand-written markdown is ignored, and a
+     * schema-invalid/corrupt fact is reported in `invalid` (not thrown) so one
+     * bad file can't break recall, capture or reindexing for the whole project.
+     * Invalid files stay on disk for manual repair.
+     */
+    scanFacts(): Promise<{
+        facts: FactFile[];
+        invalid: InvalidMemoryFile[];
+    }>;
+    /**
+     * List incident facts for the namespace, ranked by severity then recency.
+     * Unlike {@link findIncidentFactsForPaths} this does not filter by path, so
+     * callers (e.g. the context engine's project bootstrap) can surface the
+     * repository's incident hotspots before any specific edit target is known.
+     */
+    listIncidentFacts(input?: {
+        namespace?: string;
+        includeResolved?: boolean;
+    }): Promise<IncidentFactFile[]>;
+    findIncidentFactsForPaths(input: {
+        namespace?: string;
+        paths: string[];
+        includeResolved?: boolean;
+    }): Promise<IncidentFactFile[]>;
+    readSummary(pathOrId: string): Promise<SummaryFile>;
+    listSummaries(): Promise<SummaryFile[]>;
+    scanSummaries(): Promise<{
+        summaries: SummaryFile[];
+        invalid: InvalidMemoryFile[];
+    }>;
+    private scan;
+    deleteFact(id: string): Promise<void>;
+    markIncidentResolved(id: string, resolvedBy: string): Promise<void>;
+    markFactSuperseded(id: string, supersededBy: string): Promise<void>;
+    setFactSharedWith(id: string, sharedWith: string[]): Promise<void>;
+    /** Persist interaction deletion in Markdown before the derived DB is updated. */
+    markSourceInteractionDeleted(namespace: string, sourceInteractionId: string): Promise<void>;
+    /** Persist that a fact's source interaction was forgotten, keeping its provenance id. */
+    markFactSourceDeleted(id: string): Promise<void>;
+    private factPath;
+    private summaryPath;
+    private safePath;
+    private prepareDirectory;
+}
+
+type EmbeddingWorkerOptions = {
+    repository: MemoryRepository;
+    provider: ModelProvider;
+    pollIntervalMs?: number;
+    batchSize?: number;
+    maxAttempts?: number;
+    onDiagnostic?: ModelCallSink;
+};
+type ModelCallSink = (entry: ModelCallEntry) => void | Promise<void>;
+type WorkerState = "idle" | "running" | "draining" | "stopped";
+declare class EmbeddingWorker {
+    private readonly repo;
+    private readonly provider;
+    private readonly pollIntervalMs;
+    private readonly batchSize;
+    private readonly maxAttempts;
+    private readonly onDiagnostic;
+    private state;
+    private loopPromise;
+    private wake;
+    private idleResolvers;
+    private inFlight;
+    constructor(options: EmbeddingWorkerOptions);
+    getState(): WorkerState;
+    start(): void;
+    notify(): void;
+    /**
+     * Resolve once the worker reaches an empty poll (no in-flight jobs and
+     * nothing left to claim). Retained for API compatibility: with
+     * repository-side leases and backoff there is no unbounded claim window to
+     * wait out anymore.
+     */
+    drain(): Promise<void>;
+    stop(): Promise<void>;
+    shutdown(): Promise<void>;
+    getInFlight(): number;
+    private loop;
+    private flushIdleResolvers;
+    private processJob;
+    private emitDiagnostic;
+    private sleep;
+}
+
+type CodeBuddyDependencies = {
+    repository: MemoryRepository;
+    memoryFileStore?: MemoryFileStore;
+    provider?: ModelProvider;
+    worker?: EmbeddingWorker;
+    policy?: ContextPolicy;
+    tracer?: Tracer;
+};
+declare class CodeBuddy {
+    readonly config: ValidatedCodeBuddyConfig;
+    private readonly repo;
+    private readonly provider;
+    private readonly worker;
+    private readonly policy;
+    private readonly tracer;
+    private readonly memoryFileStore;
+    private namespaceId;
+    private initialized;
+    constructor(config: CodeBuddyConfig, deps?: CodeBuddyDependencies);
+    init(): Promise<CodeBuddyStatus>;
+    shutdown(): Promise<void>;
+    getWorker(): EmbeddingWorker;
+    remember(input: RememberInput): Promise<RememberResult>;
+    rememberBatch(items: RememberBatchItem[]): Promise<RememberResult[]>;
+    recall(input: RecallInput): Promise<RecallResult>;
+    /** Score only eligible file facts supplied by the context engine, without generating text. */
+    rankContextFacts(task: string, factIds: string[]): Promise<Record<string, number>>;
+    private embedQueryWithFallback;
+    /**
+     * Share facts owned by the configured namespace. A reference is a live grant
+     * recorded durably in the source fact's Markdown (`sharedWith`); a snapshot is
+     * a copy owned by the target and written to the target project's own store.
+     */
+    share(input: ShareInput): Promise<ShareResult>;
+    /** Revoke live reference shares of configured-namespace facts to `to`. */
+    unshare(input: UnshareInput): Promise<UnshareResult>;
+    /** Keep the source fact's durable `sharedWith` list in step with the shares table. */
+    private updateSharedWith;
+    forget(id: string): Promise<ForgetResult>;
+    /**
+     * Reconcile the derived database with the Markdown memory files (the source
+     * of truth) for this namespace: upsert by stable ID, preserving the file's
+     * lifecycle metadata; re-embed only changed content; delete rows whose file
+     * is gone. Only rows a reindex previously imported from Markdown
+     * (`file_backed`) are ever deleted, so DB-only legacy memory survives. Each
+     * file is applied independently: malformed or conflicting files are reported
+     * in `failures` and never abort healthy imports (nor count as deletions).
+     */
+    reindexMemory(): Promise<ReindexResult>;
+    reindexFacts(): Promise<ReindexCounts>;
+    private requireNamespaceId;
+    private writeOne;
+    private restoreShares;
+    private importFactFile;
+    private importSummaryFile;
+}
+type ReindexCounts = {
+    /** Managed files seen for this namespace (including malformed ones). */
+    scanned: number;
+    imported: number;
+    updated: number;
+    unchanged: number;
+    /** File-backed rows removed because their Markdown file is gone. */
+    deleted: number;
+    failed: number;
+};
+type ReindexFailure = {
+    kind: "fact" | "summary";
+    id: string;
+    path: string;
+    error: string;
+};
+type ReindexResult = {
+    facts: ReindexCounts;
+    summaries: ReindexCounts;
+    /** Per-file problems, capped at {@link MAX_REPORTED_FAILURES}; counts stay exact. */
+    failures: ReindexFailure[];
+};
+
+export { type AgentWriteBreakdown as A, type ShareResult as B, CodeBuddy as C, type SkipReason as D, type EmbeddingRequest as E, FACT_CATEGORIES as F, type SummaryFile as G, type SummaryFileWrite as H, INCIDENT_SEVERITIES as I, type TraceSpan as J, type Tracer as K, type ListedFact as L, type MemoryRepository as M, type NamespaceSummary as N, type UnshareResult as O, type PlannedContext as P, type QueryEmbedding as Q, type RecallInput as R, type ShareInput as S, type TextGenerationRequest as T, type UnshareInput as U, type WorkerState as V, type WorkerConfig as W, createTracer as X, isLangSmithTracingEnabled as Y, type CodeBuddyConfig as a, MemoryFileStore as b, type ModelProvider as c, type ContextPolicy as d, type PlanInput as e, type ProviderDiagnosticsHook as f, type EmbeddingResponse as g, type TextGenerationResponse as h, type CodeBuddyDependencies as i, type CodeBuddyStatus as j, type ConflictMode as k, type EmbeddingSpace as l, EmbeddingWorker as m, type FactCategory as n, type FactFile as o, type FactFileWrite as p, type ForgetResult as q, type IncidentFactFile as r, type IncidentSeverity as s, type MemoryWriteType as t, type PlannedMessage as u, type PlannerStats as v, type RecallResult as w, type RememberBatchItem as x, type RememberInput as y, type RememberResult as z };