/**
 * Preset upgrade detection — structural vs non-structural changes.
 *
 * Non-structural changes (config values, placeholder defaults) propagate
 * automatically per pin policy. Structural changes (added/removed items,
 * changed refs) require explicit `skaile preset upgrade`.
 *
 * The upgrade detector compares two preset versions and classifies the diff.
 *
 * @docLink packages/library/concepts#upgrade-strategies
 */
import type { PresetItem, PresetManifest } from "@skaile/workspaces/types/manifests";
/**
 * Classification of the diff between two preset versions.
 *
 * @docLink packages/library/concepts#upgrade-strategies
 */
export type ChangeKind = "structural" | "non-structural";
/**
 * Detailed diff between two preset manifest versions.
 *
 * @docLink packages/library/concepts#upgrade-strategies
 */
export interface PresetDiff {
    /** Overall classification — `structural` or `non-structural`. */
    kind: ChangeKind;
    /** Items added in the new version (structural). */
    addedItems: PresetItem[];
    /** Items removed from the old version (structural). */
    removedItems: PresetItem[];
    /** Items with changed refs or placeholder/materialize changes (structural). */
    changedRefItems: Array<{
        old: PresetItem;
        new: PresetItem;
    }>;
    /** Items with config-only changes (non-structural, safe to auto-propagate). */
    configChangedItems: Array<{
        old: PresetItem;
        new: PresetItem;
    }>;
    /** Human-readable summary string for CLI display. */
    summary: string;
}
/**
 * Result of {@link evaluateUpgrade} — indicates whether the upgrade can proceed automatically.
 *
 * @docLink packages/library/concepts#upgrade-strategies
 */
export interface UpgradeResult {
    /** Whether upgrade can proceed without user confirmation. */
    autoUpgradable: boolean;
    /** The computed diff between old and new. */
    diff: PresetDiff;
    /** If structural, the list of actions that require explicit user approval. */
    requiredActions?: string[];
}
/**
 * Detect changes between two preset versions.
 *
 * @param oldManifest - The currently applied preset manifest.
 * @param newManifest - The new preset manifest to upgrade to.
 * @returns Classified diff with added/removed/changed item lists.
 * @docLink packages/library/concepts#upgrade-strategies
 */
export declare function detectChanges(oldManifest: PresetManifest, newManifest: PresetManifest): PresetDiff;
/**
 * Determine if a preset upgrade can proceed automatically or needs user confirmation.
 *
 * @param oldManifest - Currently applied version.
 * @param newManifest - Target version.
 * @returns Upgrade result indicating auto-upgradability and required actions.
 * @docLink packages/library/concepts#upgrade-strategies
 */
export declare function evaluateUpgrade(oldManifest: PresetManifest, newManifest: PresetManifest): UpgradeResult;
/**
 * Apply a non-structural upgrade to existing instances.
 *
 * Updates config on existing instances to match the new preset version's
 * config/materialize/placeholder defaults. Only runs when `evaluateUpgrade`
 * returns `autoUpgradable: true`.
 *
 * @param newManifest - The new preset manifest.
 * @param existingInstances - Map of item key to instance ID.
 * @param library - Library instance used to call `updateInstance`.
 * @returns Count of updated instances and any per-instance errors.
 * @docLink packages/library/concepts#upgrade-strategies
 */
export declare function applyNonStructuralUpgrade(newManifest: PresetManifest, existingInstances: Map<string, string>, library: {
    updateInstance: (id: string, patch: {
        config?: Record<string, unknown>;
    }) => Promise<unknown>;
}): Promise<{
    updated: number;
    errors: string[];
}>;
//# sourceMappingURL=upgrade.d.ts.map