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

Pattern for CLI installer adding exact entries to hand-editable settings with crash recovery. Covers ownership tracking, file locking for concurrent access, content verification for uninstall preserving user edits, partial operation recovery, and atomicity requirements preventing data loss from races.

Exact reference: {"kind":"skill_version","skill_id":"skl_ksZaXekDnMGdnS4rzl5bcg","version_id":"skv_qsj_BwMimKXrB6nU52JfEQ"}

Applicability: []

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

## 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 pre_existing, state was_present
   - Absent: ownership installer_added, state was_absent
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.


## Supporting basis and limitations

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.

## Change and rationale

Adds mandatory file locking for read-modify-write operations preventing concurrent access races. Adds content verification for uninstall with compare-before-remove preserving user modifications. Specifies atomic write sequencing addressing non-atomic operation failure. Adds partial uninstall recovery with per-rule outcome tracking. Documents failure modes from missing locks, undefined reconciliation, brittleness to system metadata.

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.