Struct MutationLock 

pub struct MutationLock { /* private fields */ }

An exclusive ownership record for one installation domain.

The default acquisition path is fail-closed: ambiguous, malformed, oversized, or otherwise unreadable records never trigger automatic removal, and acquire never recovers a stale record at all. PID liveness alone cannot prove process identity across this public contract, so Core never treats it as proof.

Recovery is available, but only when a caller explicitly supplies StaleLockVerifier evidence through acquire_with_recovery, and only for the exact record that evidence classified.

Implementations

impl MutationLock

pub fn acquire( root: &Path, product: &ProductId, release: &ReleaseId, ) -> Result<Self>

Acquires the installation-root lock using create-new filesystem semantics.

This is the default and never recovers: an existing record always returns Error::UpdateInProgress and is left untouched.

Errors

Returns Error::UpdateInProgress when a lock record already exists, and Error::Io when the record cannot be created or written.

This entry point never recovers a record: an existing record is always contention, is never displaced, and is never deleted.

Examples found in repository

examples/stale_lock_recovery.rs (line 106)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root =
        std::env::temp_dir().join(format!("eggup-stale-lock-example-{}", std::process::id()));
    let _ = std::fs::remove_dir_all(&root);
    std::fs::create_dir_all(&root)?;

    let product = ProductId::new("example-daemon")?;
    let release = ReleaseId::new("2026.10.05")?;
    let lock_path = root.join(".eggup-mutation.lock");

    // A crashed updater left this record behind.
    std::fs::write(
        &lock_path,
        "pid=4242 nonce=9 product=example-daemon release=2026.10.05\n",
    )?;

    println!("default acquisition never recovers:");
    let error = MutationLock::acquire(&root, &product, &release).expect_err("record exists");
    println!("  {error}\n");

    // The consumer supervises pid 4242, can no longer see it, and the deployment
    // is declared idle. That combination is its proof.
    let conclusive = DeploymentVerifier {
        evidence: DeploymentEvidence {
            product: product.clone(),
            supervised: vec![4242],
            alive: Vec::new(),
            declared_idle: true,
        },
    };
    match MutationLock::acquire_with_recovery(&root, &product, &release, &conclusive) {
        Ok(lock) => {
            println!("recovered after caller proof:");
            println!("  lock record: {}", lock.path().display());
            println!("  our own record is removed when it is dropped");
        }
        Err(error) => println!("retained the record: {error}"),
    }

    // Contrast: the same record without the deployment's out-of-band statement is
    // ambiguous, so it is left exactly where it is.
    let _ = std::fs::remove_file(&lock_path);
    std::fs::write(
        &lock_path,
        "pid=5150 nonce=1 product=example-daemon release=2026.10.05\n",
    )?;
    let cautious = DeploymentVerifier {
        evidence: DeploymentEvidence {
            product: product.clone(),
            supervised: vec![5150],
            alive: Vec::new(),
            declared_idle: false,
        },
    };
    let error = MutationLock::acquire_with_recovery(&root, &product, &release, &cautious)
        .expect_err("no out-of-band proof");
    println!("\nwithout out-of-band proof:");
    println!("  {error}");
    println!("  record still present: {}", lock_path.exists());

    // And a record belonging to a different deployment is never claimed.
    let _ = std::fs::remove_file(&lock_path);
    std::fs::write(
        &lock_path,
        "pid=6060 nonce=1 product=somebody-else release=2026.10.05\n",
    )?;
    let foreign = DeploymentVerifier {
        evidence: DeploymentEvidence {
            product: ProductId::new("example-daemon")?,
            supervised: vec![6060],
            alive: Vec::new(),
            declared_idle: true,
        },
    };
    let error = MutationLock::acquire_with_recovery(&root, &product, &release, &foreign)
        .expect_err("foreign record");
    println!("\nfor another deployment's record:");
    println!("  {error}");
    println!("  record still present: {}", lock_path.exists());

    let _ = std::fs::remove_dir_all(&root);
    Ok(())
}

pub fn acquire_with_recovery( root: &Path, product: &ProductId, release: &ReleaseId, verifier: &dyn StaleLockVerifier, ) -> RecoveryResult<Self>

Acquires the lock, recovering a stale record the caller has proven stale.

The sequence is deliberately conservative:

1. create-new;
2. on an existing record, observe it within bounds;
3. ask the caller’s verifier for a verdict on that exact observation;
4. only on StaleLockDecision::ProvenStale, re-read the record and rename the pathname into a unique Eggup-owned claim path in the same directory;
5. re-read the claimed object and require it to still equal the authorized observation;
6. create-new the real lock, then delete the claimed stale record only after ownership is established.

A record that is malformed, oversized, a symlink, non-regular, or unreadable is never claimed. Active and Unknown verdicts retain the record. If the record changes before the claim, no stale deletion happens and contention is returned. If another writer creates a new lock after the claim, that writer wins and its record is never removed.

Errors

Returns RecoveryError::Core carrying Error::UpdateInProgress when the record is contended, when the caller’s verifier does not return StaleLockDecision::ProvenStale for the exact record core observed, or when another writer wins the race after a claim; and carrying Error::Io when the record cannot be created, read, or written.

Returns RecoveryError::RecoveryRequired when a displaced stale record could not be removed or verified automatically. The real retained evidence path is in RecoveryError::evidence.

Core never decides staleness itself: PID liveness, record age, executable name, and service state stay consumer policy.

Examples found in repository

examples/stale_lock_recovery.rs (line 119)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root =
        std::env::temp_dir().join(format!("eggup-stale-lock-example-{}", std::process::id()));
    let _ = std::fs::remove_dir_all(&root);
    std::fs::create_dir_all(&root)?;

    let product = ProductId::new("example-daemon")?;
    let release = ReleaseId::new("2026.10.05")?;
    let lock_path = root.join(".eggup-mutation.lock");

    // A crashed updater left this record behind.
    std::fs::write(
        &lock_path,
        "pid=4242 nonce=9 product=example-daemon release=2026.10.05\n",
    )?;

    println!("default acquisition never recovers:");
    let error = MutationLock::acquire(&root, &product, &release).expect_err("record exists");
    println!("  {error}\n");

    // The consumer supervises pid 4242, can no longer see it, and the deployment
    // is declared idle. That combination is its proof.
    let conclusive = DeploymentVerifier {
        evidence: DeploymentEvidence {
            product: product.clone(),
            supervised: vec![4242],
            alive: Vec::new(),
            declared_idle: true,
        },
    };
    match MutationLock::acquire_with_recovery(&root, &product, &release, &conclusive) {
        Ok(lock) => {
            println!("recovered after caller proof:");
            println!("  lock record: {}", lock.path().display());
            println!("  our own record is removed when it is dropped");
        }
        Err(error) => println!("retained the record: {error}"),
    }

    // Contrast: the same record without the deployment's out-of-band statement is
    // ambiguous, so it is left exactly where it is.
    let _ = std::fs::remove_file(&lock_path);
    std::fs::write(
        &lock_path,
        "pid=5150 nonce=1 product=example-daemon release=2026.10.05\n",
    )?;
    let cautious = DeploymentVerifier {
        evidence: DeploymentEvidence {
            product: product.clone(),
            supervised: vec![5150],
            alive: Vec::new(),
            declared_idle: false,
        },
    };
    let error = MutationLock::acquire_with_recovery(&root, &product, &release, &cautious)
        .expect_err("no out-of-band proof");
    println!("\nwithout out-of-band proof:");
    println!("  {error}");
    println!("  record still present: {}", lock_path.exists());

    // And a record belonging to a different deployment is never claimed.
    let _ = std::fs::remove_file(&lock_path);
    std::fs::write(
        &lock_path,
        "pid=6060 nonce=1 product=somebody-else release=2026.10.05\n",
    )?;
    let foreign = DeploymentVerifier {
        evidence: DeploymentEvidence {
            product: ProductId::new("example-daemon")?,
            supervised: vec![6060],
            alive: Vec::new(),
            declared_idle: true,
        },
    };
    let error = MutationLock::acquire_with_recovery(&root, &product, &release, &foreign)
        .expect_err("foreign record");
    println!("\nfor another deployment's record:");
    println!("  {error}");
    println!("  record still present: {}", lock_path.exists());

    let _ = std::fs::remove_dir_all(&root);
    Ok(())
}

pub fn observe(root: &Path) -> Result<Option<LockObservation>>

Observes the lock record without acquiring or removing it.

Returns Ok(None) when no record exists, and a bounded observation for a regular, non-symlink, UTF-8, in-bounds record. Records that are oversized, non-UTF-8, symlinked, non-regular, or unreadable yield Err, because Core cannot prove what they are and must therefore never displace them.

Errors

Returns Error::UpdateInProgress when a record exists that core cannot prove safe — malformed, oversized, non-UTF-8, symlinked, or non-regular — and Error::Io when the record cannot be read.

An observation never acquires, displaces, or removes anything.

pub fn inspect(root: &Path) -> Result<LockStatus>

Inspects the lock record without acquiring or removing it.

Returns LockStatus::Available when no record exists, LockStatus::Held when a bounded readable record exists, and LockStatus::Malformed when the record is missing, unreadable, oversized, or non-UTF-8. This function never deletes anything.

Errors

Returns Error::Io when the record exists but cannot be read. A malformed, oversized, symlinked, non-regular, or non-UTF-8 record is reported as LockStatus::Malformed, not as an error.

This function never deletes anything.

pub fn path(&self) -> &Path

Returns the lock record path.

Examples found in repository

examples/stale_lock_recovery.rs (line 122)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root =
        std::env::temp_dir().join(format!("eggup-stale-lock-example-{}", std::process::id()));
    let _ = std::fs::remove_dir_all(&root);
    std::fs::create_dir_all(&root)?;

    let product = ProductId::new("example-daemon")?;
    let release = ReleaseId::new("2026.10.05")?;
    let lock_path = root.join(".eggup-mutation.lock");

    // A crashed updater left this record behind.
    std::fs::write(
        &lock_path,
        "pid=4242 nonce=9 product=example-daemon release=2026.10.05\n",
    )?;

    println!("default acquisition never recovers:");
    let error = MutationLock::acquire(&root, &product, &release).expect_err("record exists");
    println!("  {error}\n");

    // The consumer supervises pid 4242, can no longer see it, and the deployment
    // is declared idle. That combination is its proof.
    let conclusive = DeploymentVerifier {
        evidence: DeploymentEvidence {
            product: product.clone(),
            supervised: vec![4242],
            alive: Vec::new(),
            declared_idle: true,
        },
    };
    match MutationLock::acquire_with_recovery(&root, &product, &release, &conclusive) {
        Ok(lock) => {
            println!("recovered after caller proof:");
            println!("  lock record: {}", lock.path().display());
            println!("  our own record is removed when it is dropped");
        }
        Err(error) => println!("retained the record: {error}"),
    }

    // Contrast: the same record without the deployment's out-of-band statement is
    // ambiguous, so it is left exactly where it is.
    let _ = std::fs::remove_file(&lock_path);
    std::fs::write(
        &lock_path,
        "pid=5150 nonce=1 product=example-daemon release=2026.10.05\n",
    )?;
    let cautious = DeploymentVerifier {
        evidence: DeploymentEvidence {
            product: product.clone(),
            supervised: vec![5150],
            alive: Vec::new(),
            declared_idle: false,
        },
    };
    let error = MutationLock::acquire_with_recovery(&root, &product, &release, &cautious)
        .expect_err("no out-of-band proof");
    println!("\nwithout out-of-band proof:");
    println!("  {error}");
    println!("  record still present: {}", lock_path.exists());

    // And a record belonging to a different deployment is never claimed.
    let _ = std::fs::remove_file(&lock_path);
    std::fs::write(
        &lock_path,
        "pid=6060 nonce=1 product=somebody-else release=2026.10.05\n",
    )?;
    let foreign = DeploymentVerifier {
        evidence: DeploymentEvidence {
            product: ProductId::new("example-daemon")?,
            supervised: vec![6060],
            alive: Vec::new(),
            declared_idle: true,
        },
    };
    let error = MutationLock::acquire_with_recovery(&root, &product, &release, &foreign)
        .expect_err("foreign record");
    println!("\nfor another deployment's record:");
    println!("  {error}");
    println!("  record still present: {}", lock_path.exists());

    let _ = std::fs::remove_dir_all(&root);
    Ok(())
}

Trait Implementations

impl Debug for MutationLock

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for MutationLock

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.