/**
 * Foreground knowledge assessment and transactional, sourced repair.
 *
 * Code placed in `packages/core/` per Package-Boundary Check — verified
 * against AGENTS.md. No repair reasoning is delegated to a background model.
 */
import type { KnowledgeCoverage, KnowledgeDoctorOptions, KnowledgeDoctorResult, KnowledgeRepairFinding, KnowledgeRepairProposal, KnowledgeRepairReceipt } from '@cleocode/contracts';
import type { OperationExecutionContext } from '@cleocode/contracts/jobs';
import type { KnowledgeRepairAttemptFailure, KnowledgeRepairCancellation, KnowledgeRepairInspection, KnowledgeRepairInventory, KnowledgeRepairInventoryQuery, KnowledgeRepairPreparation, KnowledgeRepairRecoveredState } from '@cleocode/contracts/knowledge-health';
/**
 * Validation error preserving a stable repair failure code for CLI envelopes.
 * @remarks Stale proposals and failed source validation never apply a mutation.
 * @example
 * ```ts
 * if (error instanceof KnowledgeRepairError) return error.code;
 * ```
 */
export declare class KnowledgeRepairError extends Error {
    /** Stable machine-readable repair failure code. */
    readonly code: string;
    /** Observed owned-attempt outcome and truthful persistence status. @defaultValue undefined */
    readonly attemptFailure?: KnowledgeRepairAttemptFailure;
    /** Current recovery state, separate from an unmodified historical receipt. @defaultValue undefined */
    readonly recoveryState?: KnowledgeRepairRecoveredState;
    /**
     * Construct an actionable validation or concurrency error.
     * @param code - Stable repair validation failure code.
     * @param message - Observable reason the repair was rejected.
     * @param attemptFailure - Optional observed attempt with committed or pending finalization.
     * @param recoveryState - Optional current rollback disclosure retaining authentic historical receipts.
     */
    constructor(code: string, message: string, attemptFailure?: KnowledgeRepairAttemptFailure, recoveryState?: KnowledgeRepairRecoveredState);
}
/**
 * Parse caller-supplied repair JSON against the supported operation contract.
 * @param text - JSON proposal supplied by the foreground calling agent.
 * @returns Validated proposal with an explicit supported operation.
 * @remarks Parsing does not apply repairs; source and state validation occur transactionally.
 * @example
 * ```ts
 * const proposal = parseKnowledgeRepairProposal(await readFile(path, 'utf8'));
 * ```
 */
export declare function parseKnowledgeRepairProposal(text: string): KnowledgeRepairProposal;
/**
 * Prepare a sourced existing knowledge repair without starting an executor.
 * @param context - Captured project, actor, retry identity, cancellation and shared deadline.
 * @param input - Existing supported proposal whose revision and state must still match.
 * @returns Authentic immutable pending work or the identical existing submission.
 * @throws KnowledgeRepairError when scope, source evidence or preconditions are invalid.
 * @remarks The existing job store commits proposal bytes and their digest atomically.
 * Cancellation is cooperative at guarded boundaries; admitted synchronous SQLite work
 * cannot be preempted by a timer. Preparation never changes authority or quarantine.
 * @example
 * ```ts
 * const pending = await prepareKnowledgeRepair(context, report.proposals[0]);
 * ```
 */
export declare function prepareKnowledgeRepair(context: OperationExecutionContext, input: KnowledgeRepairProposal): Promise<KnowledgeRepairPreparation>;
/**
 * Construct a repair invocation using a root and deadline captured before caller asynchronous work.
 * @param projectRoot - Explicit project identity root captured by the foreground caller.
 * @param actor - Explicit stable caller attribution; never copied from stored proposal ownership.
 * @param proposalId - Immutable proposal/retry key supplied by the caller.
 * @param deadlineAt - Original absolute invocation deadline including earlier file reads.
 * @returns Validated execution context that the caller must close in a finally block.
 * @throws KnowledgeRepairError when actor, identity or deadline input is invalid.
 * @remarks Metadata reads do not renew the deadline. This attribution is not an owner signature.
 * @example
 * ```ts
 * const context = await createKnowledgeRepairInvocation(root, actor, proposalId, deadlineAt);
 * ```
 */
export declare function createKnowledgeRepairInvocation(projectRoot: string, actor: string, proposalId: string, deadlineAt: number): Promise<OperationExecutionContext>;
/**
 * Prepare guarded recovery from a retained original receipt without applying it.
 * @param context - Explicit recovery actor, new immutable proposal identity and original deadline.
 * @param receiptId - Successful scoped original receipt whose complete affected images are retained.
 * @returns Durable immutable pending rollback through the existing preparation service.
 * @throws KnowledgeRepairError when the receipt, evidence or affected resources cannot authorize recovery.
 * @remarks Historical receipt bytes are retained; unrelated changes do not authorize overwriting an affected edit.
 * @example
 * ```ts
 * const pending = await prepareKnowledgeRollback(context, originalReceiptId);
 * ```
 */
export declare function prepareKnowledgeRollback(context: OperationExecutionContext, receiptId: string): Promise<KnowledgeRepairPreparation>;
/**
 * Apply an authentic prepared repair through the established owned job transaction.
 * @param context - Captured scope and one deadline shared by this foreground attempt.
 * @param jobId - Existing durable pending proposal or inspectable completed operation.
 * @returns Verified receipt committed with the source mutation and terminal job state.
 * @throws KnowledgeRepairError when immutable inputs, resources, generation or identity changed.
 * @remarks Uses the existing domain validators and repair ledger. Synchronous database
 * work cannot be preempted; cancellation is checked at cooperating write boundaries.
 * File hashes are rechecked around mutation but SQLite cannot lock external file edits.
 * A later explicit invocation may supply a new bounded context for the same immutable
 * proposal; an active attempt never renews its deadline. Interrupted uncommitted work
 * records observed failure/cancellation atomically when the original budget and
 * ownership permit; otherwise the error explicitly reports pending finalization
 * and retains the lease/checkpoint. No automatic retry or background reasoning runs.
 * @example
 * ```ts
 * const receipt = await applyPreparedKnowledgeRepair(context, pending.jobId);
 * ```
 */
export declare function applyPreparedKnowledgeRepair(context: OperationExecutionContext, jobId: string): Promise<KnowledgeRepairReceipt>;
/**
 * Explicitly resume immutable repair work, preserving terminal or expired running attempts before retry.
 * @param context - Fresh bounded invocation with the same explicit actor and proposal identity.
 * @param jobId - Authentic prepared job to inspect and revalidate before retry.
 * @returns Existing committed receipt or the newly committed repair receipt.
 * @throws KnowledgeRepairError when actor, source, recovery snapshot or resource preconditions changed.
 * @remarks Terminal retries retain the complete prior stored attempt atomically with a new claim.
 * An active attempt is never stolen and an expired context is never renewed. Already committed
 * effects are not reapplied. Historical outcomes and original repair evidence remain inspectable.
 * @example
 * ```ts
 * const receipt = await resumePreparedKnowledgeRepair(newInvocation, jobId);
 * ```
 */
export declare function resumePreparedKnowledgeRepair(context: OperationExecutionContext, jobId: string): Promise<KnowledgeRepairReceipt>;
/**
 * Discover durable repair jobs for one explicit principal without starting an executor.
 * @param context - Captured project, explicit actor and original invocation deadline.
 * @param query - Candidate limit, text-byte cap, lifecycle filter and scoped continuation.
 * @returns Authenticated matching identities, explicit partial diagnostics and last-scanned cursor.
 * @throws KnowledgeRepairError for missing scope or required storage/metadata failures.
 * @remarks Lease claimant labels never establish proposal authority. This page does not
 * verify current effects or load unbounded attempt ledgers; exact inspection arguments
 * expose the retained history. Independent pages are not a multi-page snapshot.
 * @example
 * ```ts
 * const page = await listPreparedKnowledgeRepairs(context, { limit: 20 });
 * ```
 */
export declare function listPreparedKnowledgeRepairs(context: OperationExecutionContext, query?: KnowledgeRepairInventoryQuery): Promise<KnowledgeRepairInventory>;
/**
 * Inspect authentic prepared work, its receipt and separate append-only attempt history.
 * @param context - Captured project, explicit original actor and immutable proposal identity.
 * @param jobId - Existing durable operation identity.
 * @param limit - Maximum lifecycle entries, default 100 and bounded to 1000.
 * @param offset - Zero-based ledger page offset, default zero.
 * @returns Actual job state and a page whose completeness is explicit.
 * @throws KnowledgeRepairError when scope, actor, proposal or persisted evidence is inconsistent.
 * @remarks This does not infer a failed outcome from lease expiry or count a cancellation request as rollback.
 * @example
 * ```ts
 * const state = await inspectPreparedKnowledgeRepair(context, jobId, 100, 0);
 * ```
 */
export declare function inspectPreparedKnowledgeRepair(context: OperationExecutionContext, jobId: string, limit?: number, offset?: number): Promise<KnowledgeRepairInspection>;
/**
 * Persist an explicit cancellation request under the original invocation budget.
 * @param context - Captured project, explicit actor and immutable proposal identity.
 * @param jobId - Existing prepared work to cancel or signal.
 * @returns Committed request status and actual observed job/receipt state.
 * @throws KnowledgeRepairError when scope or authentic prepared input is invalid.
 * @remarks Running work remains running until its owner acknowledges cancellation; completed
 * effects and receipts are preserved. Cancellation observed after commit cannot erase the request.
 * @example
 * ```ts
 * const cancellation = await cancelPreparedKnowledgeRepair(context, jobId);
 * ```
 */
export declare function cancelPreparedKnowledgeRepair(context: OperationExecutionContext, jobId: string): Promise<KnowledgeRepairCancellation>;
/**
 * List accepted sourced repairs without changing retrieval counters.
 * @param projectRoot - Canonical project root containing the repair ledger.
 * @param limit - Maximum receipts read, default 100 and capped at 1000.
 * @returns Repaired receipts that have not been rolled back.
 * @remarks Historical receipts remain stored but cannot reappear as current guidance after rollback.
 * @example
 * ```ts
 * const corrections = await listKnowledgeRepairReceipts(projectRoot, 100);
 * ```
 */
export declare function listKnowledgeRepairReceipts(projectRoot: string, limit?: number): Promise<KnowledgeRepairReceipt[]>;
/**
 * The `graph-coverage` repair finding for non-current graph coverage, or null
 * when coverage is current.
 *
 * An ownership mismatch carries its exact remedy command in
 * `coverage.nextAction` (T12659): a `--full` re-bind for a moved project
 * (same project id), or the identity check for a foreign project id. The
 * finding proposes that command, not a plain `nexus.analyze` that would
 * refuse the same mismatch again.
 *
 * @param coverage - Assessed graph coverage.
 * @returns The finding, or null.
 * @task T12659
 */
export declare function graphCoverageFinding(coverage: KnowledgeCoverage): KnowledgeRepairFinding | null;
/**
 * Assess project knowledge and optionally apply verified foreground repairs.
 * @param projectRoot - Canonical project identity root; source-root selection stays explicit.
 * @param options - Assessment budget, deterministic fix mode, sourced proposal, or receipt recovery.
 * @returns Separate health dimensions, actionable findings, proposals, and durable repair receipts.
 * @remarks Rollback conservatively checks the entire substantive project state, including unrelated later edits. Automatic repair is capped at 25 confirmed stubs and checked against the maintenance deadline before mutation.
 * @example
 * ```ts
 * const options = { fix: true, dryRun: true };
 * const report = await runKnowledgeDoctor(projectRoot, options);
 * ```
 */
export declare function runKnowledgeDoctor(projectRoot: string, options?: KnowledgeDoctorOptions): Promise<KnowledgeDoctorResult>;
//# sourceMappingURL=knowledge.d.ts.map