/** * Operator-authorized recovery of a stale effect ledger lock. * * Ledger locks (`locks/.lock`) are same-host directory locks whose * `owner` file holds `:`. A crashed writer leaves its lock behind, * and every later writer then times out rather than steal it. This module is * the only supported way to clear such a lock. It is modelled on the D16 quota * lock recovery (`recoverStaleJobQuotaLock`, `src/decision/job-quota.ts`): * * - it refuses a live owner, a PID that has been reused by a newer process, * and any owner it cannot verify (malformed owner file, permission denied); * - it needs an explicit authorization callback, which must approve the exact * inspected owner; * - it re-checks the owner after authorization and removes the lock only when * the same dead owner still holds it; * - it records the recovery in the ledger as a signed, verified effect of kind * `x.aiwg.ledger-lock-recovery` (intent before the removal, completed after * the lock-state verifier confirms it). * * @see docs/contracts/effect-ledger.v1.md "Stale lock recovery" */ import { type EffectExitCode } from './errors.js'; import { EffectLedger, type EffectReceipt } from './ledger.js'; import { type EffectVerifier } from './verifiers/types.js'; import type { EffectLinks, EffectScope, EffectVerification } from './types.js'; export declare const LOCK_RECOVERY_KIND: "x.aiwg.ledger-lock-recovery"; export declare const LOCK_RECOVERY_VERIFIER_VERSION = "1.0.0"; /** Lock names the ledger creates: one per writer, plus the checkpoint and keyring locks. */ export declare const LEDGER_LOCK_NAME_PATTERN: RegExp; export type LedgerLockOwnerState = 'dead' | 'live' | 'reused' | 'unverifiable'; export interface LedgerLockInspection { lock: string; held: boolean; state?: LedgerLockOwnerState; /** `owner-dead`, `owner-live`, `owner-pid-reused`, `owner-unreadable`, `owner-malformed`, `owner-permission-denied` or `not-held`. */ reason: string; pid?: number; /** `sha256:` over the owner file value. The value itself is never returned. */ ownerDigest?: string; lockedAt?: string; } export interface LockRecoveryOptions { /** Must approve the exact inspected owner. A throw or `false` refuses. */ authorize: (inspection: LedgerLockInspection) => Promise; links?: EffectLinks; } export type LockRecoveryOutcome = 'recovered' | 'not-held' | 'refused' | 'not-authorized' | 'recovery-in-progress'; export interface LockRecoveryResult { outcome: LockRecoveryOutcome; lock: string; inspection: LedgerLockInspection; effectId?: string; intent?: EffectReceipt; completed?: EffectReceipt | null; verification?: EffectVerification; exitCode: EffectExitCode; } export declare function lockRecoveryTarget(scope: EffectScope, lock: string): string; /** Inspect one ledger lock. Read-only. */ export declare function inspectLedgerLock(ledger: EffectLedger, lock: string): Promise; /** Inspect every lock currently present in the ledger. Read-only. */ export declare function inspectLedgerLocks(ledger: EffectLedger): Promise; /** * The lock-state verifier for recovery effects. `present` when the recovered * owner no longer holds the lock, `absent` when it still does. */ export declare function ledgerLockRecoveryVerifier(options: { projectDir: string; }): EffectVerifier; /** * Remove a stale ledger lock after explicit authorization and record the * recovery in the ledger. A live, reused or unverifiable owner is refused and * nothing is removed or recorded. */ export declare function recoverStaleLedgerLock(ledger: EffectLedger, lock: string, options: LockRecoveryOptions): Promise; //# sourceMappingURL=lock-recovery.d.ts.map