Installer ownership journal with file locking and content verification for safe uninstall

TL;DR

A CLI installer adds a fixed small set of exact entries to a settings file that a person also edits by hand. Repair and uninstall must touch only installer-added entries, never pre-existing or user-added entries, respecting explicit denies. Concurrent user edits must not cause lost updates or incorrect removals. Race from missing lock: User opens settings during install.

acquire lock
current_marker = read from settings

if matches journal marker:
  mark confirmed (write succeeded)
else:
  add missing installer_added rules
  write marker
  mark confirmed

release lock

When to use

You are seeing this: Process can crash at any point. Use this skill when you run into "Installer ownership journal with file locking and content verification for safe uninstall".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Problem

A CLI installer adds a fixed small set of exact entries to a settings file that a person also edits by hand. Repair and uninstall must touch only installer-added entries, never pre-existing or user-added entries, respecting explicit denies. Process can crash at any point. Concurrent user edits must not cause lost updates or incorrect removals.

Failures prevented

Race from missing lock: User opens settings during install. Installer reads, computes changes, writes. User saves unrelated edit, overwriting installer changes. Recovery finds marker missing, enters undefined state.

Non-atomic metadata write: Installer writes settings successfully, crashes before writing completion marker. Recovery cannot distinguish write failed from write succeeded then marker deleted.

Blind removal during uninstall: User modifies installer-owned rule before uninstall. Uninstall removes by pattern without verifying content, destroying modification.

Partial operation without progress: Uninstall processes three of six rules, crashes. Resume has no record of completed rules. Reprocessing or skipping both incorrect.

System metadata in fingerprint: Settings system adds timestamps. Fingerprint at install never matches at uninstall for unchanged rules, preventing clean uninstall.

Duplicate install: Running installer twice creates duplicate ownership claims.

Core invariants

1. Ownership decided once at install by observation, recorded, never re-derived
2. Deny overrides allow at every step, installer never touches denies
3. All operations hold advisory file lock during read-modify-write
4. Atomicity through single-write: compute changes, write once atomically
5. Content fingerprint verification: remove only if current matches recorded
6. Incremental progress: record each outcome before next step

Journal structure

In installer state directory:

operation_id: unique identifier
timestamp: when operation ran
status: pending | confirmed | removing | removed

per_rule:
  pattern: exact rule text
  action: allow or deny
  fingerprint: digest of immutable fields only
  ownership: installer_added | pre_existing  
  observed_state: was_absent | was_present | deny_blocked
  result: planned | completed | conflict | skipped

completion_marker:
  value: large random identifier
  storage: metadata_field or separate_file

file_state:
  before_digest: full file before changes
  after_digest: expected file after changes

Fingerprint only immutable fields (pattern, action), exclude system timestamps and IDs.

Install with locking

1. Acquire advisory lock
2. Read settings, compute digest

3. Classify each target:

   • Explicit deny present: ownership none, state deny_blocked
   • Already present: ownership preexisting, state waspresent
   • Absent: ownership installeradded, state wasabsent
4. Generate random completion marker
5. Write journal status pending with rules and marker, sync
6. Prepare new settings with installer_added rules and completion marker in metadata
7. Atomic write via temp and rename, sync
8. Update journal status confirmed, sync
9. Release lock

Recovery for pending operations:

acquire lock
current_marker = read from settings

if matches journal marker:
  mark confirmed (write succeeded)
else:
  add missing installer_added rules
  write marker
  mark confirmed

release lock

Uninstall with compare-before-remove

1. Acquire lock
2. Read settings, load journal
3. Create removal log status removing

4. For each installer_added rule:

   • Locate in current settings
   • If absent: log already_gone, continue
   • Compute current fingerprint
   • If matches journal: remove, log removed_match
   • If differs: preserve, log user_modified with difference
   • Write log entry, sync
5. Atomic write settings
6. Mark journal removed or partial if conflicts
7. Release lock

Recovery for removing operations:

acquire lock  
completed = get from removal log

for each installer_added:
  if in completed: skip
  else: resume from locate step

release lock

Conflict reporting

Report preserved rules: pattern, installed version, current version, reason preserved. Optional force mode overrides but logs forced actions.

Duplicate prevention

Before journal creation, search existing journals for same rules. If found and confirmed, error already installed. If pending, resume that operation.

Requirements

Do not: write settings then separately write marker (non-atomic); read without lock (race); remove without fingerprint check (destroys edits); use full file digest for detection (format changes break); include system metadata in fingerprint (false mismatches).

Required: lock before read-modify-write; prepare then write once; marker in atomic operation or readable separate file; fingerprint immutable fields only; record incremental progress.

Applicability

For file-based configuration with concurrent human editing and crash possibility. Not for: native transactions available; database with ACID; exclusive installer access; format cannot support metadata or separate files.

Support is reasoned analysis and adversarial review, not tests. Failure scenarios are observed patterns from concurrent file access, crash recovery ambiguity, installer state management. File locking follows read-modify-write race prevention. Content verification distinguishes installer-owned from user modifications. Atomicity requirements follow from crash window analysis.

Rationale: Verification identified critical issues: race conditions from missing file locks cause lost updates when user edits during operations; undefined atomicity lets crashes leave inconsistent state; blind removal destroys user edits. These are practical failure modes under normal usage. Update provides: advisory locks, single-write atomicity, content matching, incremental progress tracking surviving crashes.