Crash-safe ownership journal for installer-managed entries in a shared settings file

Not specified by the original author.

TL;DR

Delete orphan temp files carrying the installer's prefix. Run recovery first, then the old-generation removal pass.

When to use

You are seeing this: An in-place editor save between the plan read and the rename keeps the inode, passes an identity-only check, and is overwritten. Use this skill when you run into "Crash-safe ownership journal for installer-managed entries in a shared settings file".

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.

Trigger

Use this when a command-line installer writes a small fixed set of entries, typically exact-string permission allow rules, into a settings file that the developer also edits by hand and that a host application may reformat, reorder or strip unknown fields from on its own schedule. The installer must support repair, which restores what it owns, and uninstall, which removes only what it owns. No transaction spans the installer's own state and the settings file, the process can crash between the two writes, and recovery runs only at the start of the next installer command, possibly days later.

The failures this prevents

1. Uninstall removes an allow the developer had before install because it equals an installer rule.
2. Settings written before ownership is recorded leak grants after a crash, because nothing owns them.
3. Partial uninstall recovery trusts a content hash that a developer re-add reproduces, so it deletes the rule the developer just re-added by hand.
4. A re-install reclassifies the installer's own still-present entries as developer-authored, so they can never be removed.
5. Ownership tied to a path follows a repointed symlink into a file the installer never wrote.
6. A lock that survives a power loss blocks uninstall forever.
7. Uninstall removes a rule the developer edited into something else, or restores a snapshot and erases unrelated edits.
8. Uninstall removes a deny because the developer moved the owned string into the deny list and the removal search covered the whole document.
9. An in-place editor save between the plan read and the rename keeps the inode, passes an identity-only check, and is overwritten.
10. Identity tied to device and inode across commands is invalidated by every atomic editor save.
11. Repair promotes a developer-authored value to owned when a deny is lifted, or the ambiguous recovery branch deletes the journal and orphans every installer grant.
12. A conflict record has no exit, so the journal is never deleted and every later uninstall reports a conflict that no longer exists.
13. The ambiguous recovery branch never disposes of its intent, so install, repair and uninstall all refuse forever once a host strips the marker.
14. Recovery cannot tell a crash before the rename from a landed rename whose marker the host later stripped, and the optimistic reading deletes a rule the developer re-added.
15. A newer build retires an old-generation record while its string is still in the file, orphaning the grant.

Ownership model

Classify each managed rule once, at install, against the live parsed document by exact string comparison:

• PREEXISTING: already present in the allow container. Never owned, never removed, never re-added.
• DENIED: an exact deny entry matches. Never written. The deny list is read for classification only; no command adds, removes, reorders or dedupes denies.
• PENDING_ADD: absent. Becomes OWNED once the write is proven to have landed.
• UNVERIFIED: present after a write whose landing could not be proven. Needs an explicit adopt before it may be removed, and is never silently promoted or demoted.

Ownership is historical. File content may revoke ownership but never establishes it. With no journal, matching rules are reported and left alone. A fresh install never overwrites an existing OWNED or UNVERIFIED record with PREEXISTING.

Terminal states are RELEASED and RETIRED only. Every non-terminal state must have a documented exit, listed under Uninstall below. The journal is deleted only when every record is terminal.

Identify each record by exact value, the installer generation that introduced it, and an attempt sequence, so a reinstall after a conflict never collides with the lingering record. Uninstall removes as many exact copies of a value as it holds OWNED records for that value, capped at the number present.

RETIRED is reachable only from RELEASED or RELEASEDWITHCONFLICT, never directly from OWNED. Every command first treats OWNED records whose generation is older than the running build and whose value is absent from the current managed set as removal candidates, exactly as uninstall does, and retires them only after that removal attempt has reached a released state.

File identity has two scopes. Across commands, record only the resolved real path; if it now resolves elsewhere, treat every owned record as UNVERIFIED and report. Within one command, additionally pin device and inode from the plan read. Never compare device and inode across commands.

Write protocol, shared by install, repair and uninstall

1. Take a kernel-released advisory lock, such as flock or fcntl, on a dedicated lock file beside the journal for the whole command. Never lock the settings file itself, never use a create-exclusive lock file, and mark the descriptor close-on-exec.
2. Read the live document, compute the plan, snapshot the container hash, the byte digest and the within-command identity. The container hash is over the sorted multiset of canonical values in the allow container.
3. Ensure a marker exists. If the installer-namespaced marker field is absent from the live file, write one in a marker-only rename before recording any intent. A crash after this step leaves only a stray field that the next run overwrites. Without this step, recovery cannot distinguish a crash before the rename from a landed rename whose marker was stripped afterwards.
4. Write the intent record atomically: temp file, fsync, rename, directory fsync. It holds a fresh random per-operation witness, the marker value observed before this write, each effect as verbatim value with classification and recorded count, the pre-write hash and the planned post-write hash.
5. Re-read the settings file immediately before writing and abort if its byte digest or within-command identity differs from the plan snapshot. Write the settings file atomically in the real target directory. The same rename that changes the rules also writes this operation's witness into the marker field; uninstall writes its own fresh witness rather than merely deleting the install witness, so its landed verdict is a positive value match. Before the rename, re-parse the produced bytes and assert every untouched field is structurally unchanged and each touched array equals its prior contents plus or minus exactly the planned occurrences; abort otherwise. After the rename, re-read once and report if the identity differs.
6. Mark the intent committed. For uninstall, additionally mark records released, then strip the marker field in a second rename that touches nothing else, then delete the journal if every record is terminal.

Recovery verdicts

Decide the verdict before touching any rule. Compare marker values, never mere presence of the field, because an older generation's witness may remain.

• Live marker equals this intent's witness: the rename landed. Finalize from the stored verdicts. Do not re-plan.
• Live marker equals the pre-write marker recorded in the intent: the rename did not land. Discard the stored plan and re-derive from the live file, since the plan may be days old and the developer may have edited since. Never replay a stored plan.
• Live marker absent or any other value: the host or the developer removed it. Fall through to the hash branch. Absence is never treated as proof that the rename did not land.

Hash branch: live hash equals the planned post-write hash means landed; finalize. Anything else, including equality with the pre-write hash, is ambiguous because a developer who re-adds every removed value reproduces that hash. In the ambiguous branch: mutate nothing; mark each planned removal that is now absent RELEASED; mark each planned removal still present UNVERIFIED; for an install intent mark each planned addition now present UNVERIFIED and each absent one discarded; commit the intent; exit with a status distinct from success. The intent is always disposed of, so later commands proceed. UNVERIFIED is non-terminal, so the journal survives and the grants remain adoptable.

If uninstall finds a pending install intent, reconcile it to a verdict first and plan removal only for OWNED records. If install finds a pending uninstall intent, reconcile per the verdict and stop; never execute a removal plan mid-install. Delete orphan temp files carrying the installer's prefix.

Uninstall: compare before remove

Plan per OWNED effect against the live parsed document, locating by exact value never by index. Search the whole document for exact and near matches so a moved value is filed as moved rather than gone, but this search feeds the report only. Removal is scoped to the allow container. A value found in the deny container is never a removal candidate.

Within the allow container: one or more exact copies, remove exactly one per OWNED record. Zero exact copies with a near match such as an edited, narrowed, broadened or moved value: remove nothing, mark RELEASEDWITHCONFLICT and report; the developer now owns it. Zero exact copies and no near match: mark RELEASED. Near matching never feeds removal.

Exits from non-terminal states, applied on every uninstall before planning: PREEXISTING and DENIED become RELEASED, since there is nothing to remove. RELEASEDWITHCONFLICT with no exact copy and no near match becomes RELEASED. RELEASEDWITHCONFLICT with the near match still present stays put and is reported. UNVERIFIED stays put until an explicit adopt, which turns it OWNED, or an explicit disown, which turns it RELEASED. Both adopt and disown are separate commands that name the value and never run implicitly.

The write is a node-level edit of the live document. Never regenerate the file from the plan and never restore a pre-install snapshot.

Repair

Run recovery first, then the old-generation removal pass. OWNED and missing from the allow container and not denied: re-add. PREEXISTING and missing: nothing. DENIED with the deny now gone: add-if-absent; if the write lands, promote to OWNED; if the value is already present the developer put it there, so record UNVERIFIED and do not promote. A deny added later for an OWNED rule blocks repair from re-adding; uninstall still removes the installer allow.

Bounded report

One row per managed identity, meaning each rule, the marker field and the container, plus one bucket for unrecognized values. Each row carries one class chosen by fixed priority, edited over duplicated over moved over removed over matched, and a count. Rows never carry developer text. Distinct exit status on any conflict. Recovery reruns deduplicate against the report stored in the intent.

Limits

• A lock binds only other runs of the same installer. The window between the pre-rename re-read and the rename is inherent.
• A developer who deletes an owned value and retypes the identical string leaves no trace, so a later uninstall removes their copy.
• Where the host strips unknown fields, the marker step is defeated and recovery degrades to the ambiguous branch, which leaves grants in place, marks them UNVERIFIED and reports. That is the safe direction, not the correct one.
• Repair re-adds an owned rule the developer deleted deliberately. The only durable refusal is an explicit deny.
• Only one settings layer is managed.

Evidence status

Reasoned analysis only. No implementation exists and no crash injection, host reformat or editor save test has been executed. Failures 12 through 15 were found by a second independent adversarial reasoning review and confirmed by tracing the event sequences against the previous version.

Tests before shipping

Crash after the marker-only rename, after the intent write, after the settings temp write, after the rename, after journal release and after the marker strip, each crossed with a pre-existing rule, an exact deny, a developer duplicate, an edited owned rule, unrelated edits elsewhere, a host reformat and a host that strips unknown fields. Add: a conflict followed by deletion of the edited rule and a second uninstall, checking the journal reaches terminal; an ambiguous recovery followed by install, repair and uninstall, checking each proceeds; a landed rename with the marker stripped and one owned value re-added, checking nothing is removed; a newer build run as install over an old-generation owned string still present, checking it is removed before retirement; a same-generation reinstall after a conflict, checking no record collision.

Reasoned analysis only. Nothing was implemented, no crash injection or editor save test was run, and no configuration file was inspected. The design was restated in the cited conversation, then handed to one independent reasoning reviewer instructed to construct concrete failing event sequences and to withdraw any that a stated rule prevents. Each accepted finding was re-traced against the base text before inclusion. Conflict with no exit: install owns a value, the developer edits it into a near match, uninstall marks released-with-conflict and keeps the journal, the developer deletes the edited rule, and a second uninstall plans only over owned records, so the record never changes and the journal is never deleted. Ambiguous wedge: the host strips unknown fields, the uninstall rename lands, the process crashes before release, the developer adds an unrelated rule, and the next uninstall finds a hash matching neither snapshot; the base text never disposes of the intent, and both install and repair reconcile a pending uninstall intent and stop, so all three commands refuse until the developer hand-restores the exact post-write container. Window-one ambiguity: when the intent recorded no marker present before the write, a crash before the rename and a landed rename followed by a host strip are the same observation; the base text gives one branch that re-derives and one that never re-plans, and the re-derive reading removes a value the developer re-added for their own use. Retirement: the base predicate names only generation and managed-set membership, so a newer build's install can retire an owned record while its string is still in the file, and the terminal record is never planned for removal again. The reviewer also attempted and withdrew sequences targeting the marker strip against a later install witness, finalizing stored verdicts after developer edits, the read-only deny promise, and duplicate handling; each was blocked by a stated rule and no counterexample survived. One design choice was made beyond the review: a marker-only rename before the intent, so that the not-landed verdict always has positive evidence except where the host strips fields.

Rationale: The previous version guaranteed that no developer rule is deleted and no deny is touched, but it could stop working entirely. A single hand-edited owned rule left a conflict record with no transition out, and a single host strip of the marker after a landed uninstall left an intent that every command reconciled and then refused. Both arise from ordinary developer editing between install and uninstall, which is the scenario the skill exists for. The window-one ambiguity was worse: the optimistic reading re-derives from the live file and deletes a rule the developer re-added, which is the exact loss the skill promises to prevent. The retirement gap orphans grants on any build upgrade.

Not specified by the original author.

TL;DR

Keep a durable ownership journal holding classification, and a separate transient pending record describing one in-flight change. Change only owned effects in the live document. Install and repair both re-add a lapse of the first kind and both require an explicit request for an unexplained one, and neither re-adds a value a deny now covers.

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.

When to use

Use this when a command-line installer, plugin or setup script adds a fixed managed set of entries, such as exact-string tool permission allow rules, to a settings file the developer also edits by hand, and must later repair or uninstall them. It applies when the host application may reformat the same file, when recovery can happen only at the next invocation and possibly much later, when the managed set may be split across more than one file or container, and when deleting an entry the developer authored would be unacceptable.

Failures it prevents

• Uninstall deletes an entry the developer authored, because ownership was inferred from file content.
• Uninstall deletes or reverts an owned entry the developer hand-edited after install, instead of treating the edit as a transfer of ownership.
• Recovery decides a write landed from file content, and so claims an entry the developer or the host added inside the crash window. This is the same defect as inferring ownership from content, one step removed.
• A landed verdict computed over an empty set of effects is vacuously true, declaring a write landed with no evidence at all.
• A reused inode after an interrupted uninstall makes a host rewrite carry the installer's own post-rename identity, so recovery declares landed, deletes the journal and leaks every grant.
• A mistaken not-landed verdict rolls ownership back, then re-classifies the installer's own still-present entries as developer-authored, leaking every grant permanently.
• One hand-edited rule breaks unanimous corroboration for the others, so every clearly landed addition is stranded as unverified.
• A value absent from its recorded container but present elsewhere is treated as absent, goes terminal, and becomes a permanent developer entry.
• An uninstall spanning several containers is interrupted between them, and recovery either replays a plan built before the developer edited a later container or abandons the remaining containers and leaks their grants.
• A single mis-parse, or a host migration that moves the container, makes every owned entry look absent at once, and one unconfirmed observation durably lapses all of them.
• Repair treats a changed file identity as proof the host rewrote the file, but an editor that saves by temp-and-rename produces the same signal, so a grant the developer deliberately deleted is silently restored.
• The command the developer actually runs to fix things has no defined answer for a lapsed entry, so it becomes either a permanent no-op or a silent restoration of a revoked grant.
• One acknowledgement covers a batch of re-grants, so the entry the developer deliberately revoked is restored alongside the ones that were lost by accident.
• Uninstall restores a pre-install snapshot and erases unrelated later edits.
• A re-install demotes owned entries to developer entries, so their grants can never be removed.
• An older installer build retires entries a newer build owns, and the two flap on every alternation.
• A duplicate copy of a managed entry permanently withdraws the authority to remove any copy.
• An ambiguous verdict becomes absorbing, so the product can never be cleanly uninstalled.
• Two concurrent runs of the same installer overwrite each other's write-ahead record.
• A probe concludes that the host preserves unknown keys because it was read back before the host had rewritten the file, and that cached conclusion later converts an undecided verdict into a verdict that authorizes writing.
• A post-write check confirms that untouched keys are unchanged, but skips the one key the write touched, which is where damage happens.

Steps

1. Two artifacts, two lifetimes. Keep a durable ownership journal holding classification, and a separate transient pending record describing one in-flight change. The journal is deleted only once an uninstall has completed and every entry in every container is terminal. The pending record is resolved at the end of every command, including ambiguous ones. Deleting the journal at the end of a normal install leaks every grant.
2. Ownership is historical, never observational. File content may revoke ownership; it may never establish it. With no journal, matching entries are left in place and reported, never adopted. Deciding whether a write landed is an ownership judgement, so it obeys the same rule: it may not rest on content alone, and for the verdict that authorizes deleting the journal it may not rest on identity alone either.
3. Record per effect the container key path addressed by key rather than array position, the exact value and a canonical form, the occurrence count observed at plan time, the count expected after the write, a classification, and the generation of the managed set that introduced it.
4. Classify only entries the journal does not already know. Already owned stays owned, so a re-install cannot demote its own entries. A value already present becomes preexisting and is never removed. A value an explicit deny covers is blocked and never added. A value now present only in a narrower or altered form is conflicted, not added, and reported. States that record a reason rather than a history, namely blocked, lapsed and withdrawn, are re-evaluated against the current file on every run under steps 11 and 13; only owned and preexisting are exempt from re-evaluation.
5. Take an exclusive lock for the whole command. Two runs of the same installer are cooperating writers, so a lock genuinely protects against them even though it cannot bind the developer's editor or the host. If locking is unavailable, name pending records per invocation and have recovery iterate over all of them, rather than keeping one slot that a second run silently destroys.
6. Write-ahead ordering, with a witness, once per container. Build the settings temp file first and read its file identity, which the rename preserves. Persist a pending record holding the planned effects with both counts, the conflicts deliberately kept and the reason for each, the base content hash, the base file identity, the identity the temp file will carry after the rename, and the resolved target. Make the record durable with the same flush primitive used for settings. Then re-check the base hash and identity, rename, flush the directory, and only then mark the record committed. If any path between the record becoming durable and the rename exits without renaming, durably mark the record aborted; that knowledge is definitive and must not be thrown away.
7. Patch, never restore. Change only owned effects in the live document. Confirm first that parsing and re-serializing the unmodified bytes reproduces them; otherwise edit the text surgically. Before the rename, re-parse the bytes produced and assert both that every untouched key is unchanged and that each touched collection equals its prior contents minus exactly the planned occurrences of exactly the planned values. Preserve file mode, and for a linked path write beside the resolved target on the same filesystem, since a cross-device fallback would void atomicity. This is what preserves unrelated developer edits: nothing ever writes from a snapshot or from a stale plan.
8. One removal procedure, shared by every command including recovery. Compare on parsed values, never on bytes. First search the whole document for the recorded value and for near matches of it, then decide. Present in its recorded container at its recorded count means remove exactly that many. Present at a count above the recorded one means remove exactly the recorded number of occurrences: identical values are interchangeable, so counting alone guarantees no developer copy is lost. Present at a count below the recorded one, present only as a near match such as an altered pattern, a broadened or narrowed form, or the same value in a different container, means remove nothing and record a conflict; the developer's edit has transferred ownership to them. Only when neither the exact value nor a near match exists anywhere is the entry absent, which means do nothing, and it may be recorded as lapsed only under the clean-read precondition in step 11. Near matching runs before the absent test precisely so a moved or edited value cannot go terminal as absent. Near matching may only report and block additions; it must never reach the removal path. Denies are never added, edited, reordered or removed. An owned entry withdrawn because a deny now covers it is withdrawn through this same procedure, and coverage is computed by exact value only. If the deny language admits patterns, a pattern that appears to cover an owned value is an inference, so it may report and block an addition but may never authorise a removal.
9. Deciding whether the write landed. This is one bit per rename, and it must rest on a witness other writers cannot forge. Compare the file identity now at the target against the two identities recorded before the rename. The base identity means not landed, and that verdict is safe to act on alone, because a false not-landed only re-derives a plan from current state. The post-rename identity means landed only if identity carries a component that is not reused after unlink, such as file birth time together with device and inode. Where identity is device and inode alone, a matching post-rename identity is necessary but not sufficient for landed, because the orphan temp file of an interrupted uninstall can be removed and its inode reused by a later host rewrite; in that case content must also corroborate. Content corroboration requires at least two effects that are not no-ops. For removals it requires all of them absent at their recorded location. For additions it requires none of them exactly absent, where a near match counts as present, because the base count was zero and an edited value is evidence the addition arrived before it was edited. One effect cannot certify itself, since its presence and its absence are each consistent with two opposite histories. An empty set of such effects certifies nothing; treat it as a precondition failure rather than a satisfied universal. Everything else is undecided.
10. Recovery actions. Landed means finish bookkeeping only, using the effects the pending record already holds, and an entry planned for removal that is still present was re-created by the developer, so report it and leave it. Not landed, on positive evidence, means roll the journal back; any value the rolled-back plan intended to add that is nonetheless present becomes unverified, never silently preexisting, because reclassifying it as developer-authored leaks the grant forever. Then re-derive the comparison against the file as it exists now under step 8; never replay the stale plan. Undecided means change nothing in settings, but still resolve the pending record by transcribing its effects into the journal as unverified and clearing the slot: ambiguity is durable state, a write-ahead slot is not. Unverified entries need an explicit adopt before they can ever be removed, and uninstall may finish while leaving them in place, marking them terminal and exiting with a status distinct from success. Read-only commands write nothing and only report that recovery is pending, and recovery never completes an uninstall during an unrelated command.

11. Terminal is not always permanent, and absence is not always evidence. Distinguish terminal by completion, where an uninstall finished, from withdrawn, where an entry was removed for a reason that may later stop holding. An entry withdrawn because a deny covered it, or left behind by an abandoned uninstall, becomes eligible again for ordinary classification once that reason is gone; otherwise the installer is silently and permanently incomplete. A conflicted entry is retained while the variant that caused the conflict is present, and is re-reported at every later invocation. Only an explicit per-entry override naming the exact value may remove a conflicted variant; a blanket force flag is not acceptable, since one acknowledgement over a batch removes the edit the developer meant to keep alongside the ones they did not.

    An absent owned value is evidence of lapse only from a clean read: the file parsed without falling back, the recorded container resolved, and at least one other managed key was found where expected. A container that does not resolve is never evidence of lapse. A host migration to a new key path, a reinitialisation to defaults, and a dialect the host accepts but the parser does not all present as a missing container, and each lapses every owned entry in one pass. Record the first qualifying observation as a provisional lapse stamped with the file identity it was seen at, and promote it to settled only on a second qualifying observation at a different identity. A provisional lapse is resurrectable in the same way as a withdrawal; a settled one still yields to an explicit adopt.

12. Generation comparison is ordered. Retire an owned entry only when its recorded generation is strictly older than the running installer's and the entry is absent from the current managed set. A recorded generation that is newer or unrecognised means leave the entry alone and report that a newer build manages it. Keying retirement on absence from the current set alone lets an older build delete a newer build's grants.
13. Repair and install do not guess at intent, and they answer per entry. An absent owned value means the same thing in every command: lapsed. Deliberate deletion is the most common way a developer revokes a grant and it leaves no residue, so absence of evidence of intent is not evidence of accident. Record with each lapse the cause actually known, and only two causes are knowable: removed by this installer's own uninstall, or unexplained. A changed file identity is not evidence that the host rewrote the file, because an editor that saves by temp-and-rename changes identity in exactly the same way, so a lapse first seen across an identity change is still unexplained. Install and repair both re-add a lapse of the first kind and both require an explicit request for an unexplained one, and neither re-adds a value a deny now covers. Leaving install undefined here is not neutral: refusing every lapse makes install a permanent no-op after one accidental deletion, while accepting every lapse makes the request pointless, because install is the command developers run. Make the request per entry and name the exact value being restored, since one acknowledgement covering a batch restores the grant the developer revoked alongside the ones that were lost by accident.

14. One command, several containers: each container is its own commit unit. When the managed set spans more than one file or container, the command performs more than one atomic replacement, so partial completion is real. Give each container its own pending record and its own pair of recorded identities under step 6, and resolve each independently under steps 9 and 10. Because a single atomic replacement either lands whole or not at all, this confines partial state to the boundary between containers, where a per-container witness can decide it, and removes it from inside any one file.

    Three rules follow. Only the verdict survives recovery, never the plan: a not-landed container discards its recorded plan and re-derives the comparison under step 8 against the file as it exists now, because the recovery window is unbounded and the developer may have edited that container since. Resolving a pending record is not executing it: if the next command is an install rather than a retried uninstall, recovery reconciles the journal for each container and stops, so a stale removal cannot fire in the middle of an install. And terminality is per container but deletion of the journal is global, so an uninstall that finished three containers and left one undecided is not complete and must exit with the status distinct from success.

    Because every effect is decided from current state under one shared removal procedure, a re-run after any interruption converges rather than compounding, which is what makes a partial uninstall safe to simply retry.

Limits

• A lock binds only other runs of the same installer. The race with the developer's editor and with the host is narrowed by re-checking base hash and identity immediately before the rename, but a residual window is inherent to rename and cannot be closed.
• File identity built from device and inode alone is reused after unlink on common filesystems. Adding birth time makes reuse improbable but not impossible, which is why step 9 requires content corroboration for the landed verdict wherever identity may be reused. A per-write random value held in the durable journal and written into the file is the portable fallback, but a host that strips unknown keys defeats it. Detection of stripping is not a one-time probe: a host strips only when it next rewrites on its own schedule, so a probe read back promptly always reports that the key survived. Treat the probe as unproven until the file has demonstrably been rewritten by the host at least once, revalidate it when the host version changes, and while it is unproven prefer undecided over the verdict that authorises writing.
• An in-file monotonic counter is not a valid witness: it restarts after a strip and is reproduced by a restored backup or a copied settings file.
• Counting a near match as present for addition corroboration admits the case where the developer typed a similar value inside the crash window. The consequence is bounded: the entry is recorded as owned, and a later uninstall finds only a near match and keeps it as a conflict, so nothing of the developer's is removed.
• Treating every non-self lapse as unexplained means an accidental loss caused by the host requires the same per-entry request as a deliberate deletion. That is the safe direction: the request names the value and costs one confirmation, whereas the alternative silently restores revoked grants.
• Making each container a commit unit bounds partial completion but does not make the command atomic across containers. A developer who interrupts an uninstall can observe a state in which some grants are gone and some remain, and must be told that in the report rather than left to infer it.
• The undecided branch leaves grants in place, which is safe for developer data and unsafe for authority. Its report must be prominent and repeated, and the opposite trade needs an explicit override.
• Lapse confirmation costs a second invocation, so a genuine deletion is reported later than it happened. That delay is the price of not lapsing everything on one bad read.
• A developer who deletes an owned entry and retypes the identical value before any command runs leaves no trace, so a later uninstall removes their copy. This is inherent to identifying entries by exact value, not a defect the journal can repair.
• A host that canonicalises entries can turn an owned value into an apparent developer edit and orphan the grant. Recording a canonical form alongside the exact value reduces this but does not remove it.
• Restricting deny coverage to exact values means a pattern deny that genuinely shadows an owned value will not withdraw it. The entry stays owned and granted-in-name-only until the exact test matches, which is the safe direction but is not the same as correct.
• Ownership across moved or version-controlled settings files needs separate design.

Evidence status

Reasoned design only, refined across six independent reviews that were themselves carried out by reasoning. No implementation exists, and no tests or crash-injection runs have been executed. The witness mechanism in step 9 is the least settled part and should be treated as unverified; the per-container commit units in step 14 inherit that uncertainty, since they multiply the same witness rather than replacing it.

Suggested tests

• Crash injection at each step of install, repair and uninstall, with plans of zero, one, two and the full number of effects that are not no-ops.
• A developer hand-edits one owned rule and an unrelated key after install, then uninstalls, checking that the edited rule is kept and reported, the unrelated key is untouched, and the remaining owned rules are removed.
• A developer deletes one owned rule with an editor that saves by temp-and-rename, saves an unrelated edit later, then runs repair, checking that nothing is re-added without an explicit per-entry request.
• An uninstall interrupted between the pending record and the rename, followed by removal of the orphan temp file and a host rewrite that reuses its inode, checking that recovery reaches undecided rather than landed and does not delete the journal.
• An install whose rename landed but was never committed, followed by a hand edit to one owned rule and an uninstall, checking that the unedited rules are corroborated as landed and removed rather than stranded as unverified.
• An owned value moved by hand to a different container, checking that it is conflicted rather than lapsed.
• Crash injection between containers during an uninstall that spans several, with a developer edit applied to a later container inside the window, checking that the re-derived plan removes nothing the developer authored and that the run converges on retry.
• An install whose write did not land, followed by the developer or the host adding one managed value by hand before the next invocation.
• An uninstall whose write landed but was never committed, followed by the developer re-creating the values by hand.
• An interrupted uninstall followed by an install rather than a retried uninstall, checking that the journal is reconciled and no removal fires.
• A forced mistaken not-landed verdict, checking that still-present intended additions become unverified rather than preexisting.
• A host migration that moves the permissions container, and separately a dialect the parser rejects, each observed by a read-only command, checking that no lapse is recorded and that the next clean read restores normal operation.
• An accidental loss of every managed entry followed by install and then repair, checking that each entry is named and requested separately.
• A deny added after install and later removed, checked at repair and uninstall, including a pattern deny that covers an owned value without matching it exactly.
• An older installer build run against a journal written by a newer one.
• Two installer runs started concurrently against the same file.
• A duplicate copy added after install, then uninstall.
• A host-driven reformat, a host that strips unknown keys only on its own later rewrite, and a settings file copied from another machine.

Reasoned analysis only. Nothing was implemented and no tests or crash-injection runs were executed, so the procedure remains unverified in practice. The design was restated in the cited conversation, refined for the case where a developer hand-edits one owned rule and unrelated settings before uninstall, and then handed to an independent reviewer that reasoned only, read no files and ran no commands. The reviewer traced that scenario and found no failure: five matching rules are removed, the edited one is kept and reported, and unrelated keys survive the surgical patch. It found one confirmed error and three gaps, all adopted here. The confirmed error is in repair's lapse attribution. The only evidence the design offered for a host rewrite was a changed file identity, and an editor that saves by temp-and-rename produces exactly that, so a developer who deletes an owned rule and later saves any unrelated edit satisfies two clean reads at different identities and repair re-adds the revoked grant with no request. The first gap is identity reuse: after an uninstall crashes between the durable pending record and the rename, the orphan temp file can be cleaned and a later host rewrite can reuse its inode, so recovery sees the post-rename identity, declares landed, marks removals terminal and deletes the journal with all grants still present. The design already listed reuse as a limit but did not connect it to the worst outcome. The second gap is that unanimous corroboration strands landed additions when one was later edited, forcing all of them to unverified. The third gap is the unstated precedence between absent and moved. One reviewer observation was noted but not adopted as a change: read-only commands cannot resolve a pending record, which only nominally contradicts the rule that every command resolves it, since the existing text already says read-only commands only report. Acknowledged limits the reviewer did not re-count are the identical-retype case, hosts that strip unknown keys, and the residual rename race with an unlocked editor.

Rationale: The previous version reasoned correctly about the hand-edit scenario but left one confirmed error and three gaps. The lapse-cause rule offered no way to demonstrate a host rewrite except a changed identity, and that signal is produced by ordinary editors, so a deliberately revoked grant would be silently restored on the second observation. The landed verdict was declared to hold regardless of content, yet a reused inode after an interrupted uninstall lets a host rewrite present the recorded post-rename identity, and that false landed verdict deletes the journal and leaks every grant. Unanimous corroboration treated a near match on an addition as disagreement, although a near match at a base count of zero is evidence the add arrived. And the removal procedure never said whether absent or moved wins, so a moved grant could go terminal as a developer entry.

Not specified by the original author.

TL;DR

Install: journal a pending intent first, settings second, journal confirmation to owned third. Use marker equality as a secondary hint, and resolve any remaining doubt toward touching nothing and reporting. Install that meets releasing records completes the release first then proceeds with a fresh intent.

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.

When to use

Use this when a CLI installer adds a small fixed set of exact permission allow rules to a settings file that the developer also edits by hand and that may contain explicit deny rules. The installer must offer repair and uninstall that never remove a rule the user wrote, never disturb unrelated settings, and never add, remove or bypass a deny. The settings write and the ownership journal cannot share one transaction.

This is a reasoned design, corrected after two independent adversarial reviews. No executed tests back it.

Effects model

The installer owns effects, not the file. An effect is one of: an allow list entry identified by target file, exact rule string and the number of instances the installer inserted which is zero or one because the installer never inserts a string that is already present; the installer own namespaced witness entry in that file; optionally a container the installer created such as the file itself or an empty allow list recorded so uninstall can remove it only if it is still empty. Nothing else in the file is ever read for ownership or written. Every command is a structural edit: parse, change only owned effects, serialize. Never restore a pre-install snapshot; it would overwrite every unrelated edit made since.

Invariant

The journal must always claim at least as much as the installer has placed in settings, and every command runs recovery first. The invariant bounds what the journal claims. It says nothing about who wrote a string that is present now, so it never justifies removing a rule whose provenance is uncertain.

Install: journal a pending intent first, settings second, journal confirmation to owned third. Uninstall: journal a releasing intent first, settings shrink second, journal released third, journal deletion last.

Landing evidence

At intent time the installer already holds the parsed file and the plan, so it can serialize the exact bytes it will write. Record three things in the intent: the pre-write digest, the predicted post-write digest, and a fresh random marker that the write places in the witness entry. Recovery compares the current file digest: equal to the predicted digest means the write landed, equal to the pre-write digest means the write never happened, anything else means another writer touched the file. Use marker equality as a secondary hint, and resolve any remaining doubt toward touching nothing and reporting. Marker presence alone is never evidence. An older marker from a previous attempt is always present after the first install, and a host application or editor may strip an unknown entry. Only equality with the marker of this specific intent counts.

Marker verification gate for uninstall

Before removal, verify cryptographic proof of ownership. For each owned record, check that the witness marker in the current settings file equals the recorded journal marker. If the marker is absent or mismatched, set removal count to zero and report an ownership conflict. This prevents four critical failures: removing a rule the developer manually re-added with identical text after removing the installer version, removing a rule when external tools stripped the witness marker, claiming ownership of a value the developer independently set to match the installer target, and proceeding with removal when provenance is uncertain. The marker verification gate closes the ownership gap between tracking ownership via journal and enforcing removal via string matching alone.

Removal count calculation becomes: IF marker in settings does not equal journal marker THEN removal count equals zero ELSE removal count equals minimum of current exact match count and recorded insert count.

Journal records

One record per target file and exact rule string, plus one witness record per target file. States: pending, owned, preexisting, vetoed, releasing, released. Preexisting rules were present before install and are never removed or re-added. Vetoed rules had a matching deny at install and were not inserted. Released rules were removed by uninstall or were tombstoned after being observed absent, with a conflict note. Records also hold installer version, managed rule set, insert count, and the digests and marker of the current intent. Write the journal with a temporary file, flush, and atomic rename. An unparseable journal fails closed: refuse repair and uninstall, report, and require an explicit force flag whose only permitted action is removing exact managed strings with a loud report since preexisting status is unknown. Canonicalize target paths, resolving symlinks and case differences, so a second install cannot create duplicate ownership.

Recovery, run first by every command

Pending records: landed by digest or witness marker equals this intent then promote to owned, not landed by digest then discard the intent, file changed by another writer and rule absent then tombstone as released with a conflict note, file changed by another writer and rule present and marker not equal then ambiguous stay pending report and require the developer to claim or disclaim explicitly. Releasing records: landed by digest then mark released, not landed by digest then rebuild the plan from the current file and retry, file changed and rule absent then mark released, file changed and rule present and witness marker equals the recorded one then the shrink did not happen rebuild the plan and retry, file changed and rule present and witness absent or different then the shrink may have landed and the developer may have re-added the rule do not remove it mark released with the note possibly re-added by developer. Owned record with rule absent: the developer removed or edited it by hand tombstone as released. Install that meets releasing records completes the release first then proceeds with a fresh intent. Recovery is per record and per target file.

Deny handling

A deny that exactly matches a managed rule at install time vetoes insertion. Record vetoed and tell the user. A broader deny pattern does not veto; the allow is inserted and shadowed which is consistent with never touching denies. A deny added later for an owned rule blocks repair from re-adding; uninstall still removes the installer allow. The installer never adds removes or rewrites a deny under any command.

Repair

Repair requires a journal; with none report not installed rather than behaving as install. Run recovery then per record: owned and present nothing, owned and absent already tombstoned re-grant only on explicit confirmation or reinstall, preexisting and absent nothing, vetoed with the deny now gone fresh intent insert promote to owned, rules newly managed in this version fresh intent insert, rules no longer managed but still owned remove as in uninstall but rewrite the witness with a fresh marker instead of removing it while any other rule stays owned.

Uninstall: compare before remove with marker verification

One take a lock that spans the whole command from recovery through the final journal write parse the current file if it is empty or unparseable refuse to write. Two build the plan from the current parse. For each owned record verify that witness marker in settings equals journal marker. If marker absent or mismatched set removal count to zero and report ownership conflict. Otherwise remove the smaller of the recorded insert count and the current exact match count; zero matches means modified or removed by the developer so plan no change and report a conflict. Always plan removal of the witness entry if its value equals the recorded marker independent of rule records. Plan removal of a recorded container only if it is still empty. Three write the releasing intent with the plan pre-write digest predicted digest and marker in one atomic journal write. Four apply the plan to the parsed structure and touch nothing else. Five self-check: the semantic difference between the old and new parse must equal the plan exactly else abort. Re-read and abort if the digest changed since step one. Write with temporary file flush of file and directory atomic rename. Six mark records released. Delete the journal only when every record including the witness record is released preexisting or vetoed. Matching is exact string equality only. Fuzzy or prefix matching is rejected because any similarity rule can be satisfied by a user rule. An in-place edit of an owned rule is indistinguishable from delete plus user add and exact matching classifies it correctly.

Conflict report

One line per record with a fixed category: removed, left modified or removed by developer, left possibly re-added by developer, left ambiguous ownership, left preexisting, left extra duplicates, left deny present, left witness changed, left found in a different scope file, left marker verification failed. Offer a dry-run flag that prints the plan and report without writing. Use a format-preserving editor when the format supports comments and warn once that re-serialization may normalize formatting.

Known limits

A rule the developer removed and re-added by hand between commands is indistinguishable from untouched and will be removed by uninstall. Document it. If the host application deduplicates identical strings a developer duplicate of an owned rule collapses and uninstall removes the survivor. The window between the final re-read and the rename is inherent; the lock narrows it against the installer own commands only.

Anti-patterns

Treating witness presence or absence as proof of what the installer did. Removing a present rule because the journal claims it when another writer has touched the file since the intent. Silently discarding an intent when the file changed so repair re-grants a removed rule. Tracking the witness only through rule records so it is orphaned when every rule is tombstoned. Locking per write instead of per command. Restoring a pre-install snapshot on uninstall. Removing a rule that merely resembles an owned rule. Guessing ownership when the journal is unparseable. Touching deny lists for any reason. Calculating removal count without verifying marker equality first.

Supporting basis and limitations

Derived by reasoning about crash points on both sides of the settings write for install and uninstall during the journal write and between target files then checked by two independent adversarial reviews that produced concrete failing scenarios. The first review found that inferring landing from witness presence rather than from predicted digest and marker equality or resolving ambiguity in the direction that removes or claims a rule led to removing developer-written rules disclaiming installer allows and tombstoning rules the developer never saw. The second review found four failures from the missing marker verification gate at uninstall: developer manually re-adds identical rule after removing installer version uninstall removes it, external tool strips marker uninstall proceeds without proof, developer sets value to match installer target between planning and writing installer claims it, backup restore between verification and write resurrects rule but journal claims released. All scenarios are reasoning only not executed tests.

Reasoned analysis only no executed tests. Second independent adversarial review identified four definite failures from missing marker verification at removal decision point. Scenario one: developer removes installer rule then manually re-adds identical string, uninstall finds exact match and calculates minimum of one and one equals one without checking marker, removes developer rule. Scenario two: external JSON formatter or git merge strips witness marker, uninstall proceeds on string match without cryptographic proof, may remove rule developer independently added. Scenario three: developer changes setting value between installer planning step two and writing step six to match installer target, installer records insert count one and later removes developer value. Scenario four: backup restore between uninstall digest verification and atomic write resurrects rule with correct marker but journal marks released, no defined recovery path. Root cause is design tracks ownership via journal and uses marker equality for landing detection during recovery but enforces removal during uninstall based on exact string matching alone never checking marker in settings equals journal marker before removal. Predicted digest comparison definitively detects whether write landed but does not verify who wrote current content when deciding to remove it. First adversarial review corrected witness presence inference and ambiguity resolution. This update adds the marker verification gate. All scenarios reasoning not tests.

Rationale: Second adversarial review found four concrete failure scenarios where uninstall removes developer rules or claims false ownership because removal decisions use exact string matching alone without verifying cryptographic proof via marker equality. The marker verification gate closes the ownership gap between journal-based tracking and string-based enforcement.