export declare const MUTATION_ID_PATTERN: RegExp;
/** Canonical inventory of the 16 core Goal/TODO mutation tools (D-M1). */
export declare const GOAL_MUTATION_TOOL_NAMES: readonly ["create_goal", "resume_goal", "propose_goal_completion", "record_goal_oracle", "update_goal", "add_goal_todo", "add_goal_todos", "update_goal_todo", "resolve_goal_todo", "complete_goal_todo", "block_goal_todo", "split_goal_todo", "validate_goal_todo_claim", "accept_goal_todo_claim", "reject_goal_todo_claim", "recover_goal_todo_delegation"];
export type GoalMutationToolName = (typeof GOAL_MUTATION_TOOL_NAMES)[number];
export declare function isGoalMutationToolName(value: string): value is GoalMutationToolName;
export declare function isCanonicalMutationId(value: unknown): value is string;
export declare function isCanonicalMutationRequestHash(value: unknown): value is string;
/** Deterministic JSON: object keys are sorted recursively; array order and scalar values are preserved. */
export declare function canonicalGoalMutationJson(value: unknown): string;
/**
 * Canonical request hash: sha256 over canonicalGoalMutationJson(
 *   { payload: <payload minus the top-level cas field>, tool: toolName }).
 * Key order of the payload can never change the hash; unknown tools throw.
 */
export declare function hashGoalMutationRequest(toolName: string, payload: unknown): string;
export interface GoalMutationGuardInput {
    readonly mutationId: string;
    readonly expectedGoalRevision?: number;
    readonly expectedGraphRevision?: number;
    readonly expectedTodoRevision?: number;
}
export interface GoalMutationGuard {
    readonly toolName: GoalMutationToolName;
    readonly mutationId: string;
    readonly expectedGoalRevision?: number;
    readonly expectedGraphRevision?: number;
    readonly expectedTodoRevision?: number;
}
export type GoalMutationGuardFailureCode = "unknown_tool" | "invalid_mutation_id" | "invalid_revision";
export type BuildGoalMutationGuardResult = {
    readonly ok: true;
    readonly guard: GoalMutationGuard;
} | {
    readonly ok: false;
    readonly code: GoalMutationGuardFailureCode;
    readonly message: string;
};
/** Build one validated mutation guard: known tool, canonical mutationId, safe revisions. */
export declare function buildMutationGuard(toolName: string, input: GoalMutationGuardInput): BuildGoalMutationGuardResult;
export interface GoalMutationCurrentRevisions {
    readonly goalRevision?: number;
    readonly graphRevision?: number;
    readonly todoRevision?: number;
}
export type GoalMutationStaleCode = "stale_goal_revision" | "stale_graph_revision" | "stale_todo_revision";
export type ApplyGoalMutationGuardResult = {
    readonly ok: true;
    readonly status: "ok";
} | {
    readonly ok: false;
    readonly status: "stale";
    readonly codes: readonly GoalMutationStaleCode[];
} | {
    readonly ok: false;
    readonly status: "invalid";
    readonly code: "invalid_current_revision";
};
/** Compare expected guard revisions against current revisions; exact stale codes on mismatch. */
export declare function applyMutationGuard(currentRevisions: GoalMutationCurrentRevisions, guard: GoalMutationGuard): ApplyGoalMutationGuardResult;
export interface GoalMutationReceipt {
    readonly schema: "pi-goals.goal-mutation-receipt.v1";
    readonly toolName: GoalMutationToolName;
    readonly mutationId: string;
    readonly requestHash: string;
    readonly expectedGoalRevision?: number;
    readonly expectedGraphRevision?: number;
    readonly expectedTodoRevision?: number;
    readonly appliedAt: number;
    readonly bodyStored: false;
}
export type GoalMutationReceiptFailureCode = "invalid_guard" | "invalid_request_hash" | "invalid_applied_at";
export type BuildGoalMutationReceiptResult = {
    readonly ok: true;
    readonly receipt: GoalMutationReceipt;
} | {
    readonly ok: false;
    readonly code: GoalMutationReceiptFailureCode;
    readonly message: string;
};
/** Build one applied-mutation receipt echoing the guard; hash and timestamp are validated. */
export declare function buildMutationReceipt(guard: GoalMutationGuard, requestHash: string, now: number): BuildGoalMutationReceiptResult;
/** Plain receipt state keyed by mutationId; the store persists it (3b). */
export interface GoalMutationReceiptState {
    readonly receipts: Readonly<Record<string, GoalMutationReceipt>>;
}
export declare function createGoalMutationReceiptState(): GoalMutationReceiptState;
export type GoalMutationReplayOutcome = {
    readonly ok: true;
    readonly status: "new";
} | {
    readonly ok: true;
    readonly status: "replayed";
    readonly receipt: GoalMutationReceipt;
} | {
    readonly ok: false;
    readonly status: "conflict";
    readonly existingRequestHash: string;
} | {
    readonly ok: false;
    readonly status: "invalid";
    readonly code: "invalid_mutation_id" | "invalid_request_hash";
};
/**
 * Replay evaluation: same mutationId + same requestHash = idempotent replay
 * success (no re-apply); same mutationId + different hash = conflict;
 * unknown mutationId = new. Malformed ids/hashes are rejected as invalid.
 */
export declare function evaluateMutationReplay(state: GoalMutationReceiptState, request: {
    mutationId: string;
    requestHash: string;
}): GoalMutationReplayOutcome;
export type RecordGoalMutationReceiptResult = {
    readonly ok: true;
    readonly state: GoalMutationReceiptState;
} | {
    readonly ok: false;
    readonly code: "mutation_id_conflict";
    readonly message: string;
};
/**
 * Index one receipt. Re-indexing the exact same receipt is idempotent (same
 * state returned); the same mutationId bound to a different request hash is
 * a conflict and never overwrites the existing receipt.
 */
export declare function recordMutationReceipt(state: GoalMutationReceiptState, receipt: GoalMutationReceipt): RecordGoalMutationReceiptResult;