# Atomic compare-before-remove for CLI installer ownership with position-based identity markers
## When to use
Use this when a CLI installer adds a fixed set of permission rules or configuration entries to a settings file that users also edit manually. The installer must support repair and uninstall operations that remove only installer-owned rules, preserve pre-existing user rules, respect explicit denies, and handle crashes at any point without data loss or false ownership claims.
This design prevents TOCTOU races between ownership verification and removal, duplicate rule collision, and journal-settings inconsistency. Apply when user edits to owned rules must be preserved and distinguished from installer-inserted content.
This is a reasoned design from adversarial analysis, not executed tests.
## Core principles
1. **Atomicity**: Hold an advisory file lock from initial read through final write, OR use optimistic concurrency control with file version verification that aborts if the file changed between read and write.
2. **Position-based identity**: Journal records position, content, and an embedded identity marker for each inserted rule. Compare all three at uninstall. Pure content matching cannot distinguish duplicate rules.
3. **Idempotent operations**: Every operation resumes safely from crashes. Journal persists until completion. Retry uses same intent.
4. **Installation-time checks**: Before adding a rule, verify it does not already exist. Skip insertion if present, do not journal it.
## Installation steps
1. Acquire advisory file lock on settings file (or note file version for OCC).
2. Read current settings file.
3. For each rule to install:
- Check if rule already exists (content match or semantic equivalent).
- If exists, skip insertion and do not journal ownership.
- If new, embed installer-specific identity marker alongside rule.
- Determine insertion position.
4. Write journal entry recording: rule content, insertion position, embedded marker text, operation ID.
5. Write updated settings file with inserted rules and markers.
6. For OCC: verify file version unchanged since step 2. If changed, abort and retry from step 1.
7. Release file lock (if using locking).
8. Journal remains for future repair or uninstall.
## Uninstall steps
1. Acquire advisory file lock on settings file (or note file version for OCC).
2. Read current settings file.
3. Read ownership journal.
4. For each journaled rule:
- Locate rule by position range (positions may shift due to user edits).
- Verify embedded identity marker is present and matches journal.
- Compare rule content to journaled content using canonical normalization (whitespace, case as appropriate).
- If marker matches AND content matches: mark for removal.
- If either differs or rule absent: skip removal, emit conflict diagnostic.
5. Write updated settings file with owned rules removed.
6. For OCC: verify file version unchanged since step 2. If changed, abort and retry from step 1.
7. Mark journal complete only after successful removal.
8. Delete journal after completion marker persists.
9. Release file lock.
## Crash recovery
- **Crash during install before journal write**: Next install sees no journal, checks for existing rules, skips duplicates.
- **Crash during install after journal, before settings write**: Next install reads journal, verifies settings, completes insertion or marks done if already present.
- **Crash during uninstall before settings write**: Next uninstall re-reads journal, re-evaluates all rules, removes matching ones.
- **Crash during uninstall after settings write, before journal deletion**: Next uninstall sees journal, finds rules already absent, completes journal deletion.
Journal is authoritative record of intent. Every operation verifies current state before acting.
## Identity marker format
Embed installer-specific marker in settings file alongside or within each rule. Examples:
```
# Installer ID: cli-installer-v1-rule-1
allow git status
```
Or inline comment:
```
allow git status # cli-installer-v1-rule-1
```
Marker must survive user edits to surrounding content. If user removes marker, rule is no longer recognized as owned (safe default: preserve it).
## Ownership conflict reporting
When uninstall finds journaled rule with:
- Missing or different identity marker: report "rule modified or marker removed"
- Different content: report "rule content changed"
- Rule absent: silent (already removed, desired state)
Emit diagnostic, leave rule in place, proceed to next rule.
## Canonical comparison
Before comparing rule content, normalize:
- Collapse multiple spaces to single space
- Trim leading/trailing whitespace
- Apply case normalization if rules are case-insensitive
Prevents false mismatches from auto-formatting or style changes.
## File locking vs OCC
**Advisory locking**: Lock settings file with `flock` or equivalent from read through write. Prevents concurrent modifications. Requires lock support on target filesystem.
**Optimistic concurrency control**: Record file modification time or content hash at initial read. Before final write, re-check. If changed, abort transaction and retry entire operation. Does not prevent race, but detects it before data loss.
Choose based on filesystem capabilities and concurrency tolerance.
## Limits
- Requires settings file format that supports embedded comments or metadata for identity markers.
- Position-based lookup requires stable addressing (line numbers, JSON paths, etc).
- Cannot distinguish duplicate rules without identity markers.
- Advisory locks may not work on network filesystems or Windows without proper support.
- Manual user deletion of identity markers orphans those rules (uninstall cannot claim them).
## What this prevents
- TOCTOU data loss: atomicity ensures no concurrent edits lost between check and remove.
- Duplicate rule collision: identity markers distinguish installer-owned from user-added identical rules.
- Crash inconsistency: idempotent recovery completes partial operations without re-applying or double-removing.
- False ownership claims: compare verifies marker, position, and content before removal.