Crash-safe ownership journal for installer-managed settings entries

When to use

Use this when a CLI installer, plugin or setup script adds a fixed set of entries (for example exact-string tool permission allow rules) to a settings file the user also edits. It fits when the installer must later repair or uninstall those entries without deleting user entries, overriding user deny rules, or erasing unrelated edits.

Failures it prevents

• Uninstall deletes an allow the user already had before install, because ownership was inferred from the file's content.
• Uninstall restores a pre-install backup and wipes the user's later unrelated edits.
• A re-install or upgrade reclassifies owned entries as user-owned, so their grants are never removed.
• Repair silently re-grants a rule the user deliberately narrowed or removed.
• After a crash between the journal write and the settings write, recovery (possibly weeks later) deletes a rule the user re-added, or keeps grants the installer itself added.

Steps

1. External journal. Keep an ownership journal outside the settings file. Never infer ownership from settings content. Load and resolve the journal before any install, repair or uninstall.
2. Classify only unknown entries. For entries not already in the journal:

• Already present in allow: preexisting. It belongs to the user and is never removed.
• Matched by an explicit deny: blocked. Do not add it, and never edit denies.
• Otherwise: a planned add.

1. Write ahead. Before touching settings, persist a pending record containing:

• the planned change for each entry;
• the base content hash;
• the expected result hash;
• the prior committed state, so the record can be rolled back.

Every settings write needs such a record, including repair and recovery.

1. Durable ordering.
2. Fsync the journal temp file, rename it, then fsync its directory.
3. Fsync the settings temp file, re-check the base hash, rename it, then fsync its directory.
4. Only then mark the record committed.

On macOS use the full-flush fcntl, because plain fsync does not reach stable storage.

1. Patch, never restore. Change only the owned entries in the current file. Preserve other keys, array order, unknown fields, file mode and symlinks (write the temp file next to the symlink target). If parsing and re-writing the unmodified file does not reproduce it exactly, edit the text surgically or refuse.
2. Compare before remove, matching by value, not array index. Remove an owned entry only if its exact installed value is still present.

• Missing or changed: leave it alone and report a conflict. Ownership passes to the user.
• An owned allow that is now also denied: remove the allow and keep the deny.
• Duplicates: remove one copy by a fixed rule, and report that the grant still applies through the user's copy.

1. Conservative repair. Report missing owned entries. Re-add them only on explicit request.
2. Recovery at the next invocation. Decide per entry from evidence, not from a whole-file hash alone. The host application may rewrite the file itself.

• If any other change from the same atomic write is visible, the write landed. A planned removal that is still present is then a user re-add: report it and keep it.
• An entry absent at recovery is never owned.
• If nothing landed and the current command is not uninstall, roll back to the prior committed state. Read-only commands only report pending recovery.
• Use one ambiguity policy in both directions.

1. Finish uninstall in order. Mark it committed, remove other artifacts (each step safe to repeat), and delete the journal last. With no journal, leave matching entries in place and report them.

Limits

• Hash and file-identity checks narrow but do not close races with a concurrent editor or with the host application; put a limit on re-plan retries.
• When a write contains only one planned change, cross-entry evidence is unavailable. Rely on file identity and document the policy you choose.
• Journal identity across multiple, moved or version-controlled settings files needs separate design.

Evidence status

This is reasoned design plus one independent review done by reasoning. No implementation, tests or crash-injection runs back it yet.

Suggested tests

• Crash injection after each install and uninstall step, with and without later user edits.
• Re-install over an existing install.
• An owned rule edited by the user.
• A deny added after install.
• A missing journal.
• A concurrent edit between planning and rename.