/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
/**
 * graph-dynamics.ts, the runtime-dynamic dependency-graph muscles added to
 * the ONE workstream engine (the fix-phase rework; never a sibling
 * scheduler):
 *
 * - live edge addition with cycle refusal (a discovered missed dependency adds
 *   an edge; a cycle surfaces IMMEDIATELY as a structured outcome, never a
 *   silently-never-ready node);
 * - integration-conflict serialization edges (later items touching a
 *   conflicted item's files wait for its resolution);
 * - deepest-remaining-path priority (the critical path never idles);
 * - orphan detection (a blocker hard-failed past its retry bound orphans its
 *   transitive dependents, surfaced immediately, structured);
 * - the graph snapshot surfaces render (nodes, edges, states, pool state,
 *   stalled tells).
 */
import type { OrchestrationEvent, WorkItem, Workstream } from './types.js';
/** Fields shared by every edge-add outcome. */
export interface EdgeAddResult {
    readonly added: boolean;
    /** The cycle path (item titles) when the edge was refused for creating one. */
    readonly cycle?: readonly string[] | undefined;
    readonly reason?: string | undefined;
}
/** DFS: would adding `from -> dependsOn -> to` close a cycle? Returns the path when yes. */
export declare function wouldCreateCycle(workstream: Workstream, fromItemId: string, toItemId: string): readonly string[] | null;
/**
 * Add a dependency edge live (`itemId` now waits on `dependsOnId`). Refuses a
 * self-edge, an unknown endpoint, a duplicate (idempotent success), and, the
 * structured outcome, a cycle: the refusal emits `graph-cycle` naming the
 * path, so the discovery is immediate and visible, never a stuck node.
 */
export declare function addDependencyEdge(workstream: Workstream, itemId: string, dependsOnId: string, reason: string, emit: (event: OrchestrationEvent) => void): EdgeAddResult;
/**
 * Integration-conflict serialization: when `conflicted` could not merge, every
 * LATER non-terminal item that shares any of its files gains a serialization
 * edge on the conflicted item, they wait for the resolution instead of piling
 * more merges onto a known-conflicted base region.
 */
export declare function addConflictSerializationEdges(workstream: Workstream, conflicted: WorkItem, conflictFiles: readonly string[], emit: (event: OrchestrationEvent) => void): number;
/**
 * Deepest-remaining-path depth per item: the longest chain of transitive
 * DEPENDENTS below it. Claiming deepest-first keeps the critical path moving.
 */
export declare function remainingDepths(workstream: Workstream): Map<string, number>;
/**
 * Orphan pass: an item is ORPHANED when a blocker it (transitively) waits on
 * has hard-failed past its retry bound. Surfaced immediately as a structured
 * outcome (`item-orphaned`, once per item) with the blocker named, never a
 * silently-never-ready node. Returns the ids orphaned by this pass.
 */
export declare function detectOrphans(workstream: Workstream, isHardFailed: (item: WorkItem) => boolean, emit: (event: OrchestrationEvent) => void): string[];
/** The elastic-pool state a graph snapshot reports (see engine tick gating). */
export interface PoolStateSnapshot {
    readonly ready: number;
    readonly running: number;
    readonly atCap: boolean;
    readonly capKey: string;
    readonly maxSize: number;
    /** The refusal reason left on ready items when a spawn was refused (cap/policy). */
    readonly refusal?: string | undefined;
}
/** One node of the served task graph. */
export interface GraphNodeSnapshot {
    readonly id: string;
    readonly title: string;
    readonly state: string;
    readonly cluster?: string | undefined;
    readonly files: readonly string[];
    readonly mergeState?: string | undefined;
    readonly blockedReason?: string | undefined;
    readonly orphaned: boolean;
    /** Deepest-remaining-path depth (scheduling priority within the ready set). */
    readonly remainingDepth: number;
    /** Stalled tell: in-phase with no observed activity past the stall window. */
    readonly stalled: boolean;
    readonly agentId?: string | undefined;
}
export interface GraphEdgeSnapshot {
    readonly from: string;
    readonly to: string;
}
export interface WorkstreamGraphSnapshot {
    readonly workstreamId: string;
    readonly title: string;
    readonly nodes: readonly GraphNodeSnapshot[];
    readonly edges: readonly GraphEdgeSnapshot[];
    readonly pool: PoolStateSnapshot | null;
}
/** Build the surface-facing graph snapshot from live workstream state. */
export declare function buildGraphSnapshot(workstream: Workstream, pool: PoolStateSnapshot | null, isStalled: (item: WorkItem) => boolean): WorkstreamGraphSnapshot;
//# sourceMappingURL=graph-dynamics.d.ts.map