/**
 * Direct WorkGraph relation-edge queries backed by task_relations.
 *
 * This service keeps advisory relation rows separate from scheduler dependency
 * rows. Dependencies are only returned when explicitly requested, and every edge
 * is tagged with its storage source so callers cannot confuse the semantics.
 *
 * @task T10582
 * @saga T10538
 */
import type { WorkGraphRelationEdgesOptions, WorkGraphRelationEdgesResult, WorkGraphRelationQueryService, WorkGraphTaskRelationType } from '@cleocode/contracts';
export interface SqliteWorkGraphRelationReader {
    prepare(sql: string): {
        all(...params: readonly unknown[]): unknown[];
    };
}
/** Stable error code for relation rows that duplicate parent_id hierarchy. */
export declare const E_WORKGRAPH_GROUPS_AS_HIERARCHY = "E_WORKGRAPH_GROUPS_AS_HIERARCHY";
/** Stable error code for relation rows whose human rationale is absent. */
export declare const E_WORKGRAPH_RELATION_REASON_MISSING = "E_WORKGRAPH_RELATION_REASON_MISSING";
/** Stable error code for pairs modeled as both scheduler dependencies and advisory relations. */
export declare const E_WORKGRAPH_DEPENDS_RELATES_MISUSE = "E_WORKGRAPH_DEPENDS_RELATES_MISUSE";
/** Minimal relation row accepted by relation-quality validation. */
export interface WorkGraphRelationQualityRelationInput {
    readonly fromId: string;
    readonly toId: string;
    readonly relationType: WorkGraphTaskRelationType;
    readonly reason?: string | null;
}
/** Minimal dependency row accepted by relation-quality validation. */
export interface WorkGraphRelationQualityDependencyInput {
    readonly fromId: string;
    readonly toId: string;
}
/** Minimal containment row accepted by relation-quality validation. */
export interface WorkGraphRelationQualityContainmentInput {
    readonly id: string;
    readonly type: 'saga' | 'epic' | 'task' | 'subtask';
    readonly parentId?: string | null;
}
/** Diagnostic for a `groups` relation that mirrors parent_id containment. */
export interface WorkGraphGroupsAsHierarchyFinding {
    readonly code: typeof E_WORKGRAPH_GROUPS_AS_HIERARCHY;
    readonly fromId: string;
    readonly toId: string;
    readonly relationType: 'groups';
    readonly message: string;
}
/** Diagnostic for a relation edge missing a useful human-authored reason. */
export interface WorkGraphRelationReasonMissingFinding {
    readonly code: typeof E_WORKGRAPH_RELATION_REASON_MISSING;
    readonly fromId: string;
    readonly toId: string;
    readonly relationType: WorkGraphTaskRelationType;
    readonly message: string;
}
/** Diagnostic for the same task pair modeled as both dependency and relation. */
export interface WorkGraphDependsRelatesMisuseFinding {
    readonly code: typeof E_WORKGRAPH_DEPENDS_RELATES_MISUSE;
    readonly fromId: string;
    readonly toId: string;
    readonly dependencyFromId: string;
    readonly dependencyToId: string;
    readonly relationType: WorkGraphTaskRelationType;
    readonly message: string;
}
/** Typed diagnostic returned by relation-quality validation. */
export type WorkGraphRelationQualityFinding = WorkGraphGroupsAsHierarchyFinding | WorkGraphRelationReasonMissingFinding | WorkGraphDependsRelatesMisuseFinding;
/** Options for validating non-containment relation edge semantics. */
export interface WorkGraphRelationQualityValidationOptions {
    readonly nodes: readonly WorkGraphRelationQualityContainmentInput[];
    readonly relations: readonly WorkGraphRelationQualityRelationInput[];
    readonly dependencies?: readonly WorkGraphRelationQualityDependencyInput[];
}
/** Result returned by relation-quality validation. */
export interface WorkGraphRelationQualityValidationResult {
    readonly valid: boolean;
    readonly findings: readonly WorkGraphRelationQualityFinding[];
}
/**
 * Validate non-containment relation rows for semantic drift and reason quality.
 *
 * This intentionally does not validate parent_id containment shape. It catches
 * relation-specific hazards: `groups` rows that mirror hierarchy, missing human
 * reasons, and task pairs represented as both dependencies and advisory links.
 */
export declare function validateWorkGraphRelationQuality(options: WorkGraphRelationQualityValidationOptions): WorkGraphRelationQualityValidationResult;
/** SQLite implementation of direct relation-edge lookups for WorkGraph callers. */
export declare class SqliteWorkGraphRelationQueryService implements WorkGraphRelationQueryService {
    #private;
    constructor(db: SqliteWorkGraphRelationReader);
    /**
     * List direct edges around one root. `task_relations.reason` is surfaced on
     * relation edges, while dependency rows stay opt-in and reasonless.
     */
    listRelationEdges(options: WorkGraphRelationEdgesOptions): WorkGraphRelationEdgesResult;
}
/** Create a WorkGraph relation query service over an already-open SQLite DB. */
export declare function createSqliteWorkGraphRelationQueryService(db: SqliteWorkGraphRelationReader): WorkGraphRelationQueryService;
//# sourceMappingURL=relations.d.ts.map