/**
 * Reference node synchronization with Grackle entities.
 *
 * Provides lookup, upsert, and deletion of reference nodes keyed by
 * `(sourceType, sourceId)`, plus pure text-derivation helpers for
 * producing embeddable strings from entity data.
 *
 * The server-side event bus wiring that calls these functions is in #713.
 *
 * @module
 */
import { type ReferenceSource, type ReferenceNode, type Embedder } from "@grackle-ai/knowledge-core";
/** Input for syncing a reference node with a Grackle entity. */
export interface SyncReferenceNodeInput {
    /** Which entity type this refers to. */
    sourceType: ReferenceSource;
    /** The ID of the entity in Grackle's relational DB. */
    sourceId: string;
    /** Human-readable label derived from the source (e.g., task title). */
    label: string;
    /** Text content to derive the embedding from. */
    text: string;
    /** Workspace scope (empty string = global). */
    workspaceId: string;
}
/**
 * Find a reference node by its source identity.
 *
 * Uses the composite index on `(sourceType, sourceId)` for efficient lookup.
 *
 * @param sourceType - The entity type (task, finding, session, workspace).
 * @param sourceId - The entity ID from Grackle's relational DB.
 * @returns The reference node if found, or `undefined`.
 */
export declare function findReferenceNodeBySource(sourceType: ReferenceSource, sourceId: string): Promise<ReferenceNode | undefined>;
/**
 * Delete a reference node by its source identity.
 *
 * Removes the node and all its edges (`DETACH DELETE`). Used when the
 * corresponding entity is deleted in Grackle's relational DB.
 *
 * @param sourceType - The entity type (task, finding, session, workspace).
 * @param sourceId - The entity ID from Grackle's relational DB.
 * @returns `true` if a node was deleted, `false` if no matching node existed.
 */
export declare function deleteReferenceNodeBySource(sourceType: ReferenceSource, sourceId: string): Promise<boolean>;
/**
 * Upsert a reference node for a Grackle entity.
 *
 * Derives an embedding from the provided text, then either creates a new
 * reference node or updates the existing one (matched by sourceType + sourceId).
 *
 * @param embedder - The embedder to produce the embedding vector.
 * @param input - The entity data to sync.
 * @returns The node ID (either existing or newly created).
 */
export declare function syncReferenceNode(embedder: Embedder, input: SyncReferenceNodeInput): Promise<string>;
/**
 * Derive embeddable text from a task's title and description.
 *
 * @param title - The task title.
 * @param description - The task description (may be empty).
 * @returns A formatted text string suitable for embedding.
 */
export declare function deriveTaskText(title: string, description: string): string;
/**
 * Derive embeddable text from a finding's title, content, and tags.
 *
 * @param title - The finding title.
 * @param content - The finding content.
 * @param tags - Free-form tags for categorization.
 * @returns A formatted text string suitable for embedding.
 */
export declare function deriveFindingText(title: string, content: string, tags: string[]): string;
//# sourceMappingURL=reference-sync.d.ts.map