/**
 * Workflow version comparison and checkpoint diagnostics.
 *
 * Provides utilities for detecting version mismatches between stored
 * and registered workflow definitions.
 *
 * @module versioning
 */
import { WeftError } from './weft-error.ts';
import type { WorkflowVersionDiff } from './workflow-version-tuple.ts';
/** Default version string assigned when no version is specified. */
export declare const DEFAULT_WORKFLOW_VERSION = "0.0.0";
export type VersionCompatibility = 'compatible' | 'incompatible';
/**
 * Compare a stored workflow version with the currently registered version.
 *
 * - `"compatible"` — versions match; no action needed.
 * - `"incompatible"` — versions differ; the engine will throw a
 *   {@link VersionMismatchError} instead of resuming silently.
 *
 * @example
 * ```ts
 * import { checkVersionCompatibility } from '@lostgradient/weft';
 *
 * console.log(checkVersionCompatibility('1.0.0', '1.0.0')); // 'compatible'
 * console.log(checkVersionCompatibility('1.0.0', '2.0.0')); // 'incompatible'
 * ```
 */
export declare function checkVersionCompatibility(storedVersion: string, registeredVersion: string): VersionCompatibility;
/** Description of a single field-level difference between checkpoint shapes. */
export type FieldDiff = {
    field: string;
    change: 'added';
    newType: string;
} | {
    field: string;
    change: 'removed';
    oldType: string;
} | {
    field: string;
    change: 'type-changed';
    oldType: string;
    newType: string;
};
/** Shape descriptor: maps field names to their type names (e.g., `"string"`, `"object"`). */
export type ShapeDescriptor = Record<string, string>;
/**
 * Compare two checkpoint shape descriptors and return the field-level diffs.
 *
 * Returns an empty array when the shapes are identical.
 *
 * @example
 * ```ts
 * import { diffCheckpointShapes } from '@lostgradient/weft';
 *
 * const diffs = diffCheckpointShapes(
 *   { userId: 'string', count: 'number' },
 *   { userId: 'string', count: 'number', newField: 'boolean' },
 * );
 * console.log(diffs.length);        // 1
 * console.log(diffs[0]?.change);    // 'added'
 * console.log(diffs[0]?.field);     // 'newField'
 * ```
 */
export declare function diffCheckpointShapes(oldShape: ShapeDescriptor, newShape: ShapeDescriptor): FieldDiff[];
/**
 * Infer a shape descriptor from an arbitrary value by walking its top-level keys
 * and recording the `typeof` of each value.
 *
 * @example
 * ```ts
 * import { inferShape } from '@lostgradient/weft';
 *
 * const shape = inferShape({ userId: 'abc', count: 42, active: true });
 * console.log(shape['userId']); // 'string'
 * console.log(shape['count']);  // 'number'
 * console.log(shape['active']); // 'boolean'
 * ```
 */
export declare function inferShape(value: unknown): ShapeDescriptor;
/** Options for providing shape information to VersionMismatchError. */
export type ShapeDiffOptions = {
    oldShape: ShapeDescriptor;
    newShape: ShapeDescriptor;
};
/**
 * Thrown when a workflow's stored version does not match its registered
 * version.
 *
 * When shape information is provided, the error message includes a
 * field-level diff describing exactly which fields changed.
 *
 * When version tuple information is provided, the error message includes a
 * summary of which workflow, agent, or tool versions changed.
 *
 * @example
 * ```ts
 * import { VersionMismatchError } from '@lostgradient/weft';
 *
 * try {
 *   throw new VersionMismatchError(
 *     'wf-123',
 *     'orderWorkflow',
 *     '1.0.0',
 *     '2.0.0',
 *   );
 * } catch (err) {
 *   if (err instanceof VersionMismatchError) {
 *     console.log(err.storedVersion);     // '1.0.0'
 *     console.log(err.registeredVersion); // '2.0.0'
 *   }
 * }
 * ```
 */
export declare class VersionMismatchError extends WeftError<'VersionMismatchError'> {
    readonly workflowId: string;
    readonly storedVersion: string;
    readonly registeredVersion: string;
    readonly workflowType: string;
    readonly fieldDiffs: FieldDiff[] | undefined;
    readonly versionDiff: WorkflowVersionDiff | undefined;
    constructor(workflowId: string, workflowType: string, storedVersion: string, registeredVersion: string, shapeDiff?: ShapeDiffOptions, versionDiff?: WorkflowVersionDiff);
}