/**
 * State and cursor management for source-sync.
 *
 * Owns: loading/writing SourceSyncState, cursor restoration, legacy query
 * migration, token parsing, and entry count helpers. These are the only
 * functions that touch the on-disk sync state files directly.
 */
import type { AssetCatalogEntry } from "../../../types.js";
import type { SourceSyncContext, SourceSyncCursorState, SourceSyncSourceState, SourceSyncState } from "./types.js";
/**
 * Loads persisted source sync state from disk.
 * Returns a zeroed state when no file exists.
 */
export declare function loadSourceSyncState(projectRoot: string): Promise<SourceSyncState>;
/**
 * Writes the resolved sync state and (when dirty or missing) entries to disk,
 * then emits a human-readable summary to stdout.
 */
export declare function persistSourceSyncResults(projectRoot: string, nextState: SourceSyncState, entriesById: Map<string, AssetCatalogEntry>, entriesDirty: boolean): Promise<void>;
/**
 * Returns the source ids that should be treated as indexed during catalog
 * generation (partial or complete indexed sources).
 */
export declare function getIndexedSourceIds(state: SourceSyncState): Set<string>;
/**
 * Loads persisted indexed catalog entries.
 */
export declare function loadIndexedCatalogEntries(projectRoot: string): Promise<AssetCatalogEntry[]>;
/**
 * Returns the current cursor states for a source, migrating from the legacy
 * query-based format when no cursor array is present.
 */
export declare function getPreviousCursorStates(previousState: SourceSyncSourceState | undefined): SourceSyncCursorState[];
/**
 * Restores a cursor from previous state for a finite (completable) source,
 * resetting it to the initial position when the previous cursor is completed.
 */
export declare function restoreFiniteCursorState(previousCursor: SourceSyncCursorState | undefined, initialCursor: SourceSyncCursorState): SourceSyncCursorState;
/**
 * Counts catalog entries attributed to a specific source.
 */
export declare function countEntriesForSource(entriesById: Map<string, AssetCatalogEntry>, sourceId: string): number;
/**
 * Upserts a catalog entry into the context map, marking the context dirty
 * only when the entry is genuinely new or changed.
 */
export declare function upsertIndexedCatalogEntry(context: SourceSyncContext, entry: AssetCatalogEntry): void;
/**
 * Explicitly removes a single indexed catalog entry by ID, recording the
 * catalog as dirty so the change is persisted. Used by adapters that receive
 * explicit delete signals from their upstream feed (e.g. npm changes feed).
 */
export declare function deleteIndexedCatalogEntry(context: SourceSyncContext, entryId: string): void;
/**
 * Returns true when all cursors from the previous sync state have
 * `completed: true`, or when there is no previous state at all.
 *
 * Used by the orchestrator to decide whether this run constitutes a fresh
 * full re-scan (all cursors were reset to their initial positions). Only when
 * every cursor started from scratch can we trust that `observedEntryIds`
 * covers the entire source and safely prune missing entries.
 */
export declare function allPreviousCursorsCompleted(previousState: SourceSyncSourceState | undefined): boolean;
/**
 * Removes indexed entries for a source that were not observed in the latest
 * sync run, keeping the catalog accurate after item deletions upstream.
 */
export declare function pruneMissingIndexedEntriesForSource(context: SourceSyncContext, sourceId: string): void;
/**
 * Returns true when two indexed catalog entries are structurally equal,
 * independent of property key order.
 */
export declare function areIndexedCatalogEntriesEqual(left: AssetCatalogEntry, right: AssetCatalogEntry): boolean;
/**
 * Serializes `value` to JSON with all object keys sorted recursively, producing
 * a stable string suitable for deep-equality comparisons.
 */
export declare function stableStringify(value: unknown): string;
/**
 * Recursively sorts the keys of every plain object within `value`, returning a
 * structurally equivalent value with deterministic key order.
 */
export declare function sortJsonValue(value: unknown): unknown;
/**
 * Parses `value` as a base-10 positive integer, returning `fallback` when the
 * value is absent, non-numeric, or not strictly positive.
 */
export declare function parsePositiveIntegerToken(value: string | undefined, fallback: number): number;
/**
 * Parses `value` as a base-10 non-negative integer, returning `fallback` when
 * the value is absent, non-numeric, or negative.
 */
export declare function parseNonNegativeIntegerToken(value: string | undefined, fallback: number): number;
/**
 * Returns the effective max pages per source-sync run for the given context.
 *
 * Prefers `context.maxPagesPerRunOverride` when set (used by `discover index`
 * to raise the cap for a full-index build without mutating `process.env`).
 * Falls back to the runtime config value.
 */
export declare function getEffectiveMaxPagesPerRun(context: SourceSyncContext): number;