/**
 * Helpers — 核心基础层模块。
 *
 * 职责边界：
 * - 负责：safeMatchIndex 等 核心基础层职责
 * - 不负责：不属于本模块的职责由对应模块承担
 *
 * 被谁调用：引擎各子模块、管线层
 * 调用谁：无外部依赖
 *
 * 数据流：底层能力请求 → 处理 → 返回结果
 * 持久化：无持久化（纯计算/内存态）
 */
export declare function safeMatchIndex(m: RegExpMatchArray): number;
/**
 * Safe replacement for `match.groups!.xxx` — returns empty object as fallback.
 */
export declare function safeMatchGroups(m: RegExpMatchArray): Record<string, string>;
/**
 * 统一 unknown 错误为字符串。
 * 替代分散在 48+ 处的 `e instanceof Error ? e.message : String(e)` 模式。
 * 如果是 SoloForgeError 且包含 recovery 建议，自动拼接恢复提示。
 */
export declare function errorMessage(e: unknown): string;
/**
 * 安全的 JSON 解析 — 替代裸 `JSON.parse()`。
 * 解析失败时返回 fallback（默认 undefined），不会抛出异常。
 *
 * 类型安全说明：
 * - 不提供 fallback 时，返回 T | undefined — 调用方必须处理 undefined 情况
 * - 提供 fallback 时，返回 T（fallback 本身就是 T 类型）
 * - 如果传入 non-null assertion (!) 跳过 undefined 检查，属于调用方责任
 *
 * 重载签名:
 * - safeJsonParse(text) → T | undefined （不提供 fallback，解析失败返回 undefined）
 * - safeJsonParse<T>(text, fallback) → T （提供 fallback，解析失败返回 fallback 值）
 */
export declare function safeJsonParse<T>(text: string): T | undefined;
export declare function safeJsonParse<T>(text: string, fallback: T): T;
/**
 * 同步读 JSON 状态文件：ENOENT→null（合法"无记录"）；解析损坏/其他 IO 错误抛出。
 * 避免把损坏状态伪装成"无记录"：
 * "下次 readJsonFile 静默返 null 掩盖"——损坏必须显式抛，与"未创建"区分）。
 * @param filePath 文件路径
 * @param label 损坏时错误信息里的标识（如 "AgentSession" / "UpgradeState"）
 */
export declare function readStateJsonSync<T>(filePath: string, label: string): T | null;