# Four critical ownership journal failures from concurrent installs and duplicate rules

## Trigger

Use this when multiple installer components or versions might run concurrently, when developers can duplicate installer-managed rules by hand, or when digest-based crash recovery could collide with unrelated file changes. Applies to CLI installers that journal ownership of exact permission allow rules in hand-editable settings files.

## Failures prevented

### 1. Cross-component marker collision destroys ownership tracking

**Scenario:** Component A installs rule R1 with random marker M. Component B independently generates the same marker M and installs rule R2, overwriting the file. Component A's marker-based ownership verification now falsely matches Component B's witness, creating cross-contamination where A cannot detect that R1 was clobbered.

**Prevention:** Generate markers as UUID version 4 (128-bit entropy) concatenated with installer component identifier. Format: COMPONENT_ID-UUID4. Two components never generate identical markers. Journal records component-qualified marker.

### 2. Duplicate rule removal deletes developer's copy

**Scenario:** Installer owns rule R (insert count equals one). Developer manually duplicates R. Uninstall finds two exact matches, calculates removal count equals minimum of two and one equals one, but specification does not state which instance to remove. Implementation could remove developer's copy instead of installer's, especially if developer's copy appears first in array.

**Prevention:** When removal count is less than current match count, remove the last N occurrences from the array or ordered structure. Developer edits typically append or prepend; installer placement is known from journal. Removing from the end preserves earlier developer instances. Document this removal order in conflict report.

### 3. Digest collision causes false ownership claim

**Scenario:** Install crashes after writing journal pending intent but before writing settings. Developer makes unrelated edits that by astronomical chance produce a file digest matching the predicted post-install digest. Recovery compares digest, finds match, incorrectly promotes journal to owned despite rule never being written and marker never being present.

**Prevention:** Landing detection requires dual verification. Current file digest must equal predicted digest AND witness marker in settings must equal journal marker. Neither condition alone is sufficient. Only when both match is the write confirmed as landed. Update recovery algorithm to check both.

### 4. Concurrent component installs race with atomic replace

**Scenario:** Two installer components run simultaneously on same settings file. Both read empty file, compute disjoint changes. Component A atomically replaces file with its rules plus witness. Component B atomically replaces file with its rules plus witness, obliterating A's work. A's recovery finds rule absent, tombstones as released, but rule was never available to application.

**Prevention:** File-level advisory lock is insufficient when components are separate processes. Use named system-wide lock or coordination file. Before any install, acquire lock, check for in-progress operations from other components via their journal pending states in shared directory, either wait or coordinate. Alternative: change from atomic file replacement to merge-based structural edit where each component owns a namespaced section.

## Corrected algorithms

**Marker generation:**
```
component_id = installer component identifier
uuid = generate UUID version 4
marker = component_id + "-" + uuid
record marker in journal intent
write marker to witness field in settings
```

**Landing detection with dual verification:**
```
current_digest = hash of current settings file
current_marker = witness marker value from current settings

if current_digest equals predicted_digest AND current_marker equals journal_marker:
  write landed, promote to owned
else if current_digest equals pre_write_digest:
  write never happened, discard or retry intent
else:
  another writer changed file, use recovery rules for ambiguous state
```

**Duplicate rule removal with last-N strategy:**
```
exact_matches = find all occurrences of rule pattern in settings
current_count = length of exact_matches
recorded_insert_count = journal insert count
removal_count = minimum of current_count and recorded_insert_count

if removal_count is greater than zero:
  remove last removal_count occurrences from exact_matches
  log removed instances count, preserved instances count
```

**Cross-component coordination:**
```
acquire system-wide named lock for settings file path
scan shared journal directory for all components
if any component has pending or removing state with recent timestamp:
  decide: wait with timeout, coordinate via merge, or error
proceed with operation holding lock
release lock only after journal updated to stable state
```

## Conflict report additions

When duplicate rule preserved: "Rule PATTERN: removed last N of M instances, N developer duplicates preserved."

When marker mismatch blocks removal: "Rule PATTERN: marker verification failed, ownership unproven, preserved."

When cross-component operation detected: "Component OTHER_ID operation in progress, coordinated via lock."

## Known limits

UUID version 4 collision probability is negligible but nonzero. Last-N removal strategy assumes developer edits occur at boundaries, not middle of array. Cross-component coordination requires shared journal directory accessible to all components. Digest plus marker dual verification adds file read overhead to every recovery.

## Requirements

Marker entropy: minimum 128 bits, use cryptographic random source. Component ID: stable across installer versions, distinct per independently-installed component. Lock scope: system-wide not process-only. Removal order: deterministic and documented. Recovery: check both digest and marker, never decide on one alone.

## Applicability

Use when installer has multiple components, when users commonly duplicate rules, when file can be modified during crash window creating digest collision risk, or when advisory file locks alone proved insufficient for preventing races. Complements but does not replace file locking and content verification patterns.