47 KiB

Raw Blame History

Framing — `apply_resource_op` delete destroys unsaved work

Revision 2. Status: PROPOSED — needs explicit user approval before implementation. DO NOT implement, DO NOT merge. Lane: resource-op-delete-guard, worktree ../pmacs-resource-op-delete, based on githubsucks/main @ ad41cf1 (re-checked at revision 2: no drift, main is still ad41cf1).

This is a live data-loss bug, reproduced four ways against ad41cf1 (§1.1). A language server can destroy a buffer's unsaved edits and the file that would have held them, with no prompt, no status message, and no error return.

This PR is the implementation PR. Revision 2 drops revision 1's framing-PR-then-implementation-PR plan, which conflicted with one-feature/one-branch/one-PR. The framing is revised in place; once the design is approved, the implementation lands on this same branch and in this same PR (§8).

Revision history

Revision 1 → 2, after review round 1

The refusal strategy was approved in principle; revision 1 as written was not. Q#RD1 (refuse unconditionally) and Q#RD5 (take prefix-awareness now) are settled yes; Q#RD9 is settled no and is withdrawn. Six blocking points, all accepted, plus three further overclaims found by the sweep the review asked for.

Q#RD2 conflated inspection with removal — rewritten. Revision 1 proposed removing the buffer before the filesystem call. That fires arbitrary Lua on_removed callbacks while the file still exists, destroying today's useful invariant that a subscriber observes the path already gone, and it accepts losing the buffer if the deletion then fails. The correct sequence separates the two: stat/no-op → enumerate and validate → mutate filesystem → reconcile. Validation needs no removal, so a failed deletion leaves the buffer intact automatically. The review is right and revision 1 was wrong. Buffer::editing_in_progress() (src/buffer.rs:747) is a public getter, so the re-entrancy condition can also be checked during validation rather than discovered during removal.
Q#RD3 overclaimed whole-batch atomicity — rewritten and downgraded. Revision 1 called the preflight "whole-batch atomicity" and said "nothing in the batch is mutated". That is false for a sequential batch: an earlier text edit can dirty a clean buffer, and an earlier rename can move a modified buffer into a later delete's subtree, after the snapshot was taken. The preflight is now described as an early conflict check — a cheap, honest first filter, not a transaction (§2.1, Q#RD3). The real robustness comes from per-op pcall and an always-sent response (Q#RD7).
The lookup cannot be EditorCore::find_buffer_for_path — accepted and independently re-verified. It normalizes but delegates to BufferRegistry::find_by_path (src/buffer_registry.rs:168), whose own doc says "First buffer bound to path" — singular, insertion order. And pmacs.buffer.from_file (src/lua_bindings/mod.rs:3112) calls create_from_bytes with no dedup check, so duplicate path-bound buffers are reachable from public Lua. A clean first match hides a modified second. Q#RD6 now requires a full scan.
Do not expand the parked lifecycle defect — accepted. Revision 1 left it ambiguous whether a recursive delete should reconcile descendants. It must not: mode (d)'s dangling-window and last-buffer defects would be promoted from exact-path to tree-wide. Q#RD5 now says explicitly that the tree is inspected but only the exact path is reconciled.
Q#RD4 must hold at both layers — accepted. Revision 1 applied the ignore_if_not_exists early return only to the primitive. The Lua preflight must not reject an absent path merely because a modified buffer still names it.
The prompt argument was overclaimed — rewritten, and this was my error. Revision 1 said prompting was "architecturally unavailable", "the only option that is possible", and that the server-initiated path "cannot produce that answer". All three are wrong. pmacs.lsp.send_response (src/lua_bindings/mod.rs:9680) takes request_id as an ordinary value, so a workspace/applyEdit can be answered on a later tick; and a callback continuation would reuse the existing minibuffer shadow (rung 4), not add a seventh rung. The honest claim is that prompting is expensive and separately scoped, and §2.2 now argues only that, on evidence (§1.8).

Three further overclaims found by the sweep (the review asked for the defect class, not just the three cited instances — all three are the same shape: revision 1 asserted an absence or a guarantee it had not established):

"There is no *Messages* buffer and no *warnings* buffer" was misleading by omission. There is a durable append-only error surface: LuaHost::append_to_errors_buffer (src/lua.rs:401) writing *errors* (ERRORS_BUFFER_NAME, src/lua.rs:32; 49 references across src/ and builtin/), already used by log_hook_error (src/lua_bindings/mod.rs:6061), log_statusline_provider_error (:6099) and log_buffer_removed_error. This improves the design: Q#RD7 now records the refusal there too, so it survives the status line being cleared and leaves a trace on the unattended path.
"Only path 1 is fully unattended" understated the problem. Revision 1 said a raise on paths 2 and 3 "propagates out of the pmacs.async coroutine" without establishing where it lands. It lands nowhere useful: step (builtin/runtime/async.lua:196) routes an uncaught coroutine error to pmacs.error, which is undefined — 11 call sites in builtin/, zero definitions — so the error(...) fallback re-raises at the spawn site. No caller reliably reports a raise, which strengthens rather than weakens point 2's requirement.
pmacs advertises no workspace.workspaceEdit capability at all. default_client_capabilities (src/lsp.rs:3242) sends "applyEdit": true but no workspaceEdit object, so no documentChanges, no resourceOperations, and no failureHandling — grep -rn failureHandling over the tree returns 0. Revision 1 discussed batch semantics without noting that pmacs declares no failure-handling strategy. Named as ground truth (§1.11); not fixed here (§6).

Revision 1

First cut. Established the bug and the four modes, the caller inventory, the Emacs prior art, and the refusal recommendation.

0. Coherence impact (COHERENCE §20)

Journey step 6, "Receive language intelligence" (§2), and by consequence step 5, "Edit immediately" — the loss is of exactly the edits step 5 grades as "genuinely excellent". §2's verdict table grades step 6 Partial; this lane does not raise that grade, it removes a way the step can destroy the user's work. Serves Priority 1 ("treat regressions as release blockers") as a correctness floor rather than a feature.
Interaction islands: none added. The recommended design adds no modal surface at all — it refuses and reports. Revision 2 correction: revision 1 additionally claimed that the rejected prompt option would have added a seventh dispatcher rung. It would not; a callback continuation reuses the existing minibuffer shadow (rung 4). The count stays at six either way, and §6's island budget is not an argument against prompting (§2.2).
Config registry: not adopted. No knob is proposed; the refusal is unconditional (Q#RD1). An lsp.confirm-server-edits-style setting is the natural future adopter and is parked in §6.
Background-work attribution: unchanged.
No audited claim in COHERENCE.md changes, so under §25 no COHERENCE edit rides this PR. The docs/active-work.md lane for this PR does ride it, per that file's "When a PR is opened, give it a lane."

1. Ground truth (scouted and verified @ `ad41cf1`)

1.1 The bug, reproduced

pmacs.buffer.apply_resource_op with kind = "delete" destroys a modified buffer and the file backing it. Reproduced in this worktree by throwaway acceptance tests against ad41cf1, written, run, then removed — they are the model for §5's pins, not shipped artefacts. Four modes:

(a) The reported bug.

PRE: modified=true text="UNSAVED EDIT ORIGINAL ON DISK\n"
apply_resource_op result: Ok(())
buffers before=3 after=2
file still on disk? false

The call returns Ok(()). The file is gone. The buffer is gone. The text existed in exactly one place and now exists nowhere.

(b) ignore_if_not_exists = true destroys the buffer having done no filesystem work at all. When the path is already absent, the delete arm skips the remove_file — and falls through to the buffer reconciliation anyway:

file gone; buffers=3; buffer holds the only copy
result: Ok(())
buffers after=2
CONFIRMED: ignore_if_not_exists=true did ZERO fs work yet still destroyed the only copy.

The create arm returns early (return Ok(())) under the analogous ignore_if_exists condition; the delete arm's Err(NotFound) branch does not return.

(c) recursive = true fails in the opposite direction.

recursive delete result: Ok(())
inner file exists? false
buffers before=3 after=3
inner buffer still in registry? true

The tree goes; no buffer is reconciled, because the lookup is for the directory path and buffers hold file paths. The most destructive arm does the least reconciliation. Here the data survives — in an orphaned buffer — which is strictly safer than (a), and is why the fix must not be "make delete behave like the recursive case".

(d) Removal is not kill_buffer.

victim is the active buffer? true
window.buffer():is_valid() after delete => Ok(Boolean(false))
editor.file_path() after delete => Ok(Nil)

buffers now: 1
delete of the LAST buffer: Ok(())
buffers after: 0  (0 => registry driven empty)

EditorCore::kill_buffer (src/editor_core.rs:4590) refuses the last buffer and rebinds every window to a fallback. This path does neither. (d) is parked (§6, Q#RD8) and, per Q#RD5, must not be widened by this lane.

1.2 There is no dirty check at any link in the chain

The delete arm (src/lua_bindings/mod.rs:3313) — stats, deletes, then find_by_path, then remove_buffer_and_fire. No is_modified.
remove_buffer_and_fire (:1592) — registry.remove(id) then after_buffer_removed (:1602), which clears keymaps, config, folds and fires on_removed. No dirty check.
BufferRegistry::remove (src/buffer_registry.rs:127) — one guard, and not this one:
```
if let Some(buf) = self.buffers.get(&id)
    && buf.editing_in_progress()
{
    return Err(RegistryError::ConcurrentEdit { ... });
}
```
That refuses re-entrant removal from inside an edit intercept (T M7.4). It says nothing about unsaved content.

The report's description is accurate at every link. Modes (b), (c) and (d) are additional.

1.3 The ordering is disk-first, so no guard placed later can help

The arm performs the irreversible filesystem operation before it has looked for a buffer. A fix that adds a dirty check to the existing buffer-reconcile block is not a fix — it converts mode (a) into mode (c), and the user's file is still gone. The check must happen in a phase that precedes the filesystem call, which is what Q#RD2 introduces.

1.4 `is_modified` is available, singular, and the lookup around it is not

One field, Buffer::is_modified: bool (src/buffer.rs:164); one accessor (:473); one public mutator mark_clean (:488). Buffer::editing_in_progress() (:747) is likewise a public getter, so both conditions Q#RD2 needs are inspectable without mutating.
Zero features refuse or confirm on unsaved state today. kill_buffer, editor.quit (whose editor.before-quit veto hook has no subscriber) and dired.revert all ignore it; the only behavioural consumer is autosave's gather filter (src/autosave.rs:363), which includes rather than refuses. This lane introduces the first refusal keyed on unsaved state and should be read as setting that precedent.
The registry lookup is singular and duplicates are reachable. BufferRegistry::find_by_path (src/buffer_registry.rs:168) returns the first match in insertion order — its own doc says "First buffer bound to path". EditorCore::find_buffer_for_path (src/editor_core.rs:935) normalizes and then delegates to it, so it inherits the singularity. And duplicates are creatable from public Lua: pmacs.buffer.find_or_open (src/lua_bindings/mod.rs:3162) dedups via find_by_path, but pmacs.buffer.from_file (:3112) does not — it calls create_from_bytes unconditionally and then set_buffer_path. Two from_file calls on one path yield two path-bound buffers, and a clean first match hides a modified second. This is why Q#RD6 requires a full scan rather than the existing wrapper.
Lua reaches modified state as buf:is_modified() (:1261) and pmacs.describe.buffer(id).modified (:6359). It is not a key on the pmacs.buffer module table, so the preflight needs a new query (Q#RD3).

1.5 Who calls this, and what happens to a raised error

One production caller: apply_workspace_edit (builtin/runtime/lsp.lua:1301), at :1346. Three callers of that:

#	Call site	Origin	Disposition of a raise
1	`handle_server_requests` (`lsp.lua:1815`), call at `:1836`	server-initiated `workspace/applyEdit`	Swallowed. The pump runs under `pcall(handle_server_requests)` (`:1892`); the raise unwinds past the `pcall(pmacs.lsp.send_response, ...)` that answers the request, so the user sees nothing and the server is never answered.
2	LSP rename (`lsp.lua:2311`)	user, `M-x`	Raises out of the `pmacs.async` coroutine — see below.
3	code action apply (`lsp.lua:2373`)	user, `M-x`	as #2.

Revision 2 correction. Revision 1 called only path 1 unattended. Paths 2 and 3 are no better: step (builtin/runtime/async.lua:196) handles an uncaught coroutine error by calling pmacs.error if it exists and error(...) otherwise —

if not ok then
  if pmacs.error then
    pmacs.error("pmacs.async: coroutine raised: " .. tostring(yielded))
  else
    error("pmacs.async: coroutine raised: " .. tostring(yielded))
  end
  return
end

— and pmacs.error is undefined: 11 call sites across builtin/, zero definitions. So the fallback always runs and re-raises at the spawn site. No caller reliably surfaces a raise to the user. Hence Q#RD7: the refusal travels as a value, never as an exception alone.

src/rename.rs:25 documents the division of labour — rename.rs parses and never mutates; Lua drives the primitives "so the application strategy stays configurable". That strategy is what this framing picks.

1.6 A partial batch is already possible today — verified

The applier's loop (lsp.lua:1340-1349) calls the primitive unprotected. Two delete ops where the second raises:

batch result: Err(... "apply_resource_op delete: No such file or directory (os error 2)")
a.txt still exists? false (false ⇒ partial batch)

The first op stayed applied. Partial application on I/O error is the status quo, not something a refusal introduces. Data loss is strictly worse than a failure class the code already tolerates.

It also shows the preflight's contract is narrower than its comment implies. lsp.lua:1287-1291 says the applier "refuses to mutate anything unless every URI it touches resolves to a real file path first". True — but URI resolution is the only precondition; the plan loop (:1302-1336) validates nothing about the filesystem or the registry. That loop is where Q#RD3's conflict check goes.

1.7 The batch is sequential, and the protocol says so

Claims about the LSP specification (3.18), not about pmacs:

"If resource operations are present, clients need to execute the operations in the order in which they are provided."
FailureHandlingKind.Abort: "All operations executed before the failing operation stay executed."
FailureHandlingKind.TextOnlyTransactional: "If the workspace edit contains only textual file changes they are executed transactionally. If resource changes are part of the change the failure handling strategy is abort."

So the protocol itself declines to promise transactionality for exactly the edits this lane is about. This is the evidence that revision 1's "whole-batch atomicity" claim was unsupportable, and the reason Q#RD3 now describes an early conflict check instead. Sequential execution is also why a snapshot preflight is necessarily incomplete: an earlier op can change the facts a later op's precondition was evaluated against.

1.8 What prompting would actually cost — corrected

Revision 1 called prompting impossible. It is not. Establishing what is and is not true:

True, and verified:

The primitive cannot suspend. apply_resource_op is a synchronous Rust closure performing its std::fs calls inline; there is no yield point. A prompt therefore cannot be issued from inside it — the applier would have to be restructured into a continuation chain.
pmacs.minibuffer.read (src/lua_bindings/mod.rs:13380) is asynchronous-by-callback, and Minibuffer::accept (src/minibuffer.rs:334) deliberately returns the callback rather than invoking it, because "firing user code from inside the minibuffer would re-enter the registry" (:332).
The minibuffer is a single slot that replaces without asking. Minibuffer::session: Option<MinibufferSession> (src/minibuffer.rs:71), and begin (:106) is documented "Replaces any existing session". A prompt raised mid-batch while the user has a minibuffer open silently destroys the in-flight prompt and its callbacks.
There is no y_or_n helper in the tree — a named deferral (docs/dired-framing.md:854).

False, as revision 1 had it:

"The server-initiated path cannot produce that answer." It can. pmacs.lsp.send_response (src/lua_bindings/mod.rs:9680) takes (server_id, request_id, result, err) as ordinary values; nothing binds it to the pump's call frame, and request_id arrives on the event as a plain Lua value that can be stashed. A workspace/applyEdit can be answered on a later tick.
"It costs a seventh dispatcher shadow." It does not. The minibuffer is already rung 4; a continuation reuses it.

So the honest case against prompting (§2.2) is scope, not possibility: queuing, cancellation, collision with an already-active single-slot minibuffer, and revalidation of every precondition after the user turn — because the world moves during the turn, which is §1.7's problem again, only worse.

1.9 Autosave cannot serve as a pre-delete backup

Verified against src/autosave.rs: there is no per-buffer write entry point (the only public writer is sweep, :261, which walks the whole registry); sweep skips clean buffers (:363); removing a buffer purges its recovery file — the on_removed callback registered at builtin/runtime/autosave.lua:167 calls discard_buffer (:511), with a sweep-time GC backstop (:290-306), pinned by tests/autosave_acceptance.rs:702; and deleting the file flips the recovery to Stale, which is never auto-offered.

1.10 Report channels — corrected

pmacs.editor.set_status (src/lua_bindings/mod.rs:13036) is transient; it is cleared at the top of every dispatch_key.
Revision 2 correction: a durable surface exists. LuaHost::append_to_errors_buffer (src/lua.rs:401) appends to *errors* (ERRORS_BUFFER_NAME, src/lua.rs:32), creating it on first use, and is the established idiom for "a callback failed and the user was not watching" — log_hook_error (src/lua_bindings/mod.rs:6061), log_statusline_provider_error (:6099), log_buffer_removed_error, and the config error path (src/lua_bindings/config.rs:511). Revision 1 claimed no such channel existed. It does, it is Rust-side, and Q#RD7 now uses it.

1.11 pmacs advertises no `workspace.workspaceEdit` capability

default_client_capabilities (src/lsp.rs:3242) sends "applyEdit": true (:3259) inside its "workspace" block (:3253) but no workspaceEdit object at all. So pmacs declares neither documentChanges ("The client supports versioned document changes in WorkspaceEdits"), nor resourceOperations ("The resource operations the client supports"), nor failureHandling ("The failure handling strategy of a client if applying the workspace edit fails") — grep -rn "failureHandling" over the tree returns 0.

Two consequences worth stating plainly. pmacs applies resource operations it never declared support for; and it declares no failure strategy, so §1.7's Abort semantics are the de facto behaviour by omission rather than by choice. Neither is fixed by this lane — declaring capabilities changes what servers send, which is a behavioural change needing its own evidence (§6). It is recorded because a framing about batch failure semantics that did not notice pmacs declares none would be describing half the system.

1.12 The rename arm is more careful, and differently careful

"rename" (src/lua_bindings/mod.rs:3291) does std::fs::rename, then find_by_path, then set_buffer_path — it rebinds, preserving contents and modified state. Delete destroys. Rename treats the buffer as the valuable thing and the path as a mutable attribute; delete treats the buffer as a cache of the file.

Both arms share the §1.4 lookup defects. docs/dired-framing.md:807-819 and the dired Stage 1 entry under "Closed since the last snapshot" in docs/active-work.md claim the rename side for dired Stage 2. §6 draws the boundary; the dired lane is recorded as OPEN, STALE, DO NOT MERGE AS-IS and under re-scout, which is why this lane does not wait on it.

1.13 Prior art — claims about Emacs, not pmacs

Verified against lisp/progmodes/eglot.el, emacs-mirror/emacs master.

Eglot orders the operations the other way round. Its do-delete:

(do-delete (path &key recursive ignoreIfNotExists &allow-other-keys)
  (let ((exists (file-exists-p path)))
    (when (and (not exists) (not ignoreIfNotExists))
      (eglot--error "File %s does not exist" path))
    (when exists
      ;; Kill buffer if the file is visited
      (let ((buf (find-buffer-visiting path)))
        (when buf (kill-buffer buf)))
      (delete-file path recursive))))

The buffer is killed before the file is deleted, and in Emacs kill-buffer on a modified file-visiting buffer prompts — so the consent gate precedes the irreversible step. (Eglot ignores kill-buffer's return value, so declining still deletes the file, but the buffer and its text survive. Even that failure mode is milder than pmacs's.) Note also that the exists guard means ignoreIfNotExists does not fall through to the buffer kill — the asymmetry mode (b) exposes in pmacs.

Revision 2 note: Emacs's ordering is not what Q#RD2 adopts. Emacs can afford buffer-first because kill-buffer is itself the consent gate; pmacs has no such gate, so it validates first and reconciles last (Q#RD2), which yields the same safety without firing callbacks against a file that still exists.

Eglot confirms server-initiated edits by default, as a whole-batch decision taken before anything is applied. eglot-confirm-server-edits defaults to '((t . maybe-summary)); prepare builds closures touching nothing, then the decision, then apply-all. The maybe-* decisions skip the prompt only when the batch is peaceful:

(peaceful
 (and
  all-text-edits
  (cl-loop for op in prepared
           always (find-buffer-visiting (cadddr op)))))

all-text-edits is a conjunction over the whole batch, so a batch containing any create/rename/delete always prompts under the default.

1.14 `apply_resource_op` has no direct test coverage

grep -rn "apply_resource_op" tests/ src/ returns 4 lines: one doc comment in src/rename.rs and three inside the binding's own definition. Zero tests name it.

One indirect acceptance exercises it: m4_15_workspace_edit_resource_ops_apply_in_order (tests/m4_acceptance.rs:4014), driven by the resourceops mode of the fake server (src/bin/pmacs_fake_lsp.rs:834). Its deleted c.rs is never opened, so the entire buffer-reconciliation half is untested. That suite and that fake are where §5's pins belong.

2. The decision space

2.1 Recommended — validate before mutating, at the primitive; conflict-check early, in the applier

The primitive refuses before touching disk. The applier catches what it can early, and reports honestly what it cannot.

Layer 1 — the primitive (the invariant). The delete arm becomes four ordered phases:

stat / no-op decision  →  enumerate and validate affected buffers
                       →  mutate the filesystem
                       →  reconcile the registry

Validation inspects; it does not remove. If any affected buffer is modified — or is mid-edit (editing_in_progress) — the op returns an error having touched nothing. Because validation removes nothing, a filesystem failure leaves every buffer intact automatically, and on_removed still fires only in the reconcile phase, i.e. with the path already gone, preserving today's invariant.

Layer 2 — the applier (early conflict check + robust reporting). apply_workspace_edit's existing plan loop gains a modified-buffer conflict check for delete ops and returns its existing nil, message. This is a filter, not a transaction (§1.7): it catches the common case cheaply, before anything is mutated, and it is honest that a sequential batch can still refuse mid-flight. What makes mid-flight refusal survivable is Q#RD7: each primitive call is wrapped, every failure becomes nil, message, the origin buffer is restored best-effort, and the unattended caller always answers the server.

Neither layer is redundant. Layer 1 alone leaves every batch failure reported through a channel that does not work (§1.5). Layer 2 alone leaves the primitive armed for direct callers — pmacs.buffer.apply_resource_op is public Lua API, and dired Stage 2's own plan names delete reconciliation as its 2a substrate.

Why this beats the runners-up, in one sentence each: it is the only option that puts the check strictly before the irreversible step without either firing callbacks into a half-changed world (buffer-first) or inventing a recovery surface (backup), and it is the only one whose cost is bounded by this lane.

2.2 Prompt the user — rejected on scope, not on possibility

Revision 2 rewrite. Revision 1 argued impossibility on three grounds; two were wrong (§1.8) and are withdrawn. The surviving argument is narrower and is about cost:

The applier must become a continuation chain. The primitive cannot suspend (§1.8), so the remaining plan has to be carried as a closure across the user turn — with cancellation, and with revalidation of every precondition afterwards, because the world moves during the turn. That is §1.7's sequential-batch problem with a human-scale delay inserted into it.
The minibuffer is a single slot that replaces without asking (Minibuffer::begin, "Replaces any existing session"). A prompt raised while the user is mid-M-x destroys their in-flight prompt. Queuing is therefore a prerequisite, and no queue exists.
Deferred answers need a pending-request ledger. Answering workspace/applyEdit later is possible (§1.8) but means retaining (server_id, request_id) across ticks and deciding what happens if the server dies first. purge_dead_pending exists for client requests; there is no equivalent for held server requests.

None of that is impossible; all of it is a separate lane with its own framing. Refusing is the correct move for a live data-loss bug, and a prompt can later loosen an unconditional refusal without either change invalidating the other.

2.3 Save first, then delete — rejected

Silently converts an unsaved edit into a committed one and then destroys it — more destructive, not less, because it overwrites the on-disk original immediately before removing the file. It also cannot be relied on: save_inner (src/editor_core.rs:1908) refuses at :1917 when the file changed on disk since it was read, so the fallback question is unanswered and we are back to refusing.

2.4 Back up the contents somewhere recoverable — rejected

Rejected on evidence (§1.9): the decisive fact is that removing the buffer deletes the recovery file, so the backup is destroyed by the operation it exists to survive. Building a side-store outside autosave/ means a second recovery surface with its own discovery, GC and lifecycle, to make a destructive operation feel safe.

2.5 Key the behaviour on LSP-versus-user provenance — rejected

apply_resource_op takes no provenance argument and there is no ambient caller identity. Adding one makes the primitive's safety depend on a caller-supplied flag — any caller that omits it is unguarded, which is the failure mode the lane exists to remove. COHERENCE §10 (extension trust classes) is unbuilt, so there is no trust dimension to key on. The refusal is unconditional and provenance-blind.

3. Decisions

Q#RD1 — Refuse. Do not prompt, do not save, do not back up — SETTLED YES

A delete whose target set contains a modified buffer fails, changing nothing on disk and nothing in the registry. This is the first refusal in the codebase keyed on unsaved state (§1.4) and is intended as the precedent for kill_buffer and editor.quit, which have the same gap.

Q#RD2 — Validate before mutating; reconcile last — REWRITTEN at rev 2

Four phases, in order: stat/no-op decision → enumerate and validate affected buffers → mutate the filesystem → reconcile the registry.

Validation inspects only. It checks Buffer::is_modified() and Buffer::editing_in_progress() (src/buffer.rs:473, :747) across the affected set. Nothing is removed, so nothing can be lost if a later phase fails.
editing_in_progress moves from discovery to validation. Today a ConcurrentEdit refusal from BufferRegistry::remove arrives after the file is gone. Checking it during validation means a delete invoked from inside the target's own edit intercept refuses before disk.
on_removed still observes the path already gone. Reconciliation is the last phase, so the invariant revision 1 would have broken is preserved. This is the specific defect revision 1's buffer-first ordering introduced, and it is why that ordering is withdrawn.
A filesystem failure leaves buffers untouched, automatically rather than by compensation.

Q#RD3 — The preflight is an early conflict check, not a transaction — DOWNGRADED at rev 2

apply_workspace_edit's plan loop gains a modified-buffer conflict check for delete ops and returns its existing nil, message. It is described in the code comment and here as a filter:

What it guarantees: when the conflict is visible at plan time, nothing in the batch is mutated at all, and the user gets one clear message.
What it does not guarantee, stated plainly: documentChanges are sequential (§1.7). An earlier text edit can dirty a clean buffer, and an earlier rename can move a modified buffer into a later delete's subtree, after the snapshot. Then the preflight passes and the primitive refuses mid-batch, leaving earlier operations applied — which is FailureHandlingKind.Abort, the strategy the spec itself assigns to any edit containing resource changes.
Revision 1 called this "whole-batch atomicity" and said "nothing in the batch is mutated". That was false and is withdrawn.

The check needs a path-keyed modified query that Lua lacks (§1.4). It must be one query shared with the primitive's validation phase, so the two cannot drift apart.

Q#RD4 — `ignore_if_not_exists` short-circuits at both layers — WIDENED at rev 2

When the path is absent and ignore_if_not_exists is set, the op is a no-op:

Primitive: return early without touching the registry — the create arm's existing idiom and Eglot's exists guard (§1.13).
Preflight: must not reject the batch merely because a modified buffer still names that absent path. Revision 1 applied this only to the primitive, which would have made the preflight refuse an op the primitive treats as a no-op — a refusal with no underlying destruction, i.e. a false positive that blocks legitimate edits.

Mode (b) is not a special case of the main bug; it is a missing early return, and a fix aimed only at the "we actually deleted something" branch leaves it live.

Q#RD5 — Recursive deletes are inspected tree-wide but reconciled exact-path — SETTLED YES, NARROWED at rev 2

Mode (c) proves recursive = true reconciles nothing, so an exact-path guard is bypassed by the most destructive arm. Therefore:

Validation is prefix-aware: every buffer whose path lies beneath the deleted directory is inspected, and any modified one refuses the op. Without this the guard has a trivial reachable bypass.
Reconciliation is not widened: after a successful clean recursive delete, descendant buffers are left exactly as today — orphaned and clean. Removing them now would promote mode (d)'s dangling-window and last-buffer defects from an exact-path defect to a tree-wide one, which is precisely the parked lifecycle work this lane must not expand into (Q#RD8).

The asymmetry is deliberate and is the point: inspect widely, mutate narrowly.

Boundary with dired. docs/dired-framing.md:807-819 and the ledger claim prefix-aware, normalize-before-lookup rebinding for the rename side. This lane takes the delete side only. Taking it now rather than consuming dired Stage 2's helper is settled, and is supported by the ledger's own assessment of that lane: PR #171 is OPEN, STALE, DO NOT MERGE AS-IS, 153 commits behind at the last snapshot, under re-scout. Whichever lands second adopts the first's helper.

Q#RD6 — The shared query scans all path-bound buffers — REWRITTEN at rev 2

Revision 1 said the guard would use EditorCore::find_buffer_for_path. That is wrong and is withdrawn: it normalizes but delegates to the singular, first-match-only find_by_path (§1.4), and duplicate path-bound buffers are reachable from public Lua via pmacs.buffer.from_file. A clean first match would hide a modified second — a silent guard bypass.

The shared query therefore:

scans every path-bound buffer, returning all matches rather than the first;
normalizes once and compares normalized forms, so a raw-path lookup cannot miss a stored normalized path;
matches with component-aware Path::starts_with, not string prefix — so /tree does not match /tree-sibling;
is the single query used by both the primitive's validation phase and the Lua preflight (Q#RD3).

"Modified" is Buffer::is_modified(). No new notion of dirtiness.

Explicitly not guarded: a clean buffer. A delete whose target is open but unmodified proceeds and removes the buffer, as today. Overreach would break m4_15 and would fail legitimate deletes for users who merely have the file open.

Q#RD7 — Failures travel as values, are always answered, and leave a durable trace — WIDENED at rev 2

§1.5 established that no caller reliably surfaces a raise. So:

Every primitive call inside apply_workspace_edit is wrapped, and every execution failure — refusal or I/O error — is converted to the existing nil, message return. No exception escapes the applier.
The origin buffer is restored best-effort on the failure path too. Today pcall(pmacs.buffer.find_or_open, origin) runs only after a successful loop; an early failure return would strand the user in whatever buffer the last op left active.
The unattended caller always answers. Path 1 must send { applied = false, failureReason = ... } in every failure case. Today the raise unwinds past the send and the server waits forever.
The refusal is also recorded in *errors* via the existing Rust-side append_to_errors_buffer idiom (§1.10), so it survives the status line being cleared on the next keystroke and leaves a trace on the path the user was never watching.
The message names the buffer and says what to do. Not a bare errno.

Q#RD8 — The window/last-buffer defects do not land here

Mode (d) is real and parked (§6). It is a different failure from data loss, and it is shared with pmacs.buffer.remove.

The trap that makes the obvious fix wrong: the two removal paths clean disjoint sets. kill_buffer handles the last-buffer refusal, round_trip_buffers, side-window collapse and window rebinding, but not keymaps, config, folds or on_removed callbacks; remove_buffer_and_fire handles exactly the latter and none of the former. Neither is a superset, so "just call kill_buffer instead" would silently regress four cleanups. Unifying them needs its own census and its own lane — and per Q#RD5 this lane must not enlarge the surface that lane will have to fix.

Q#RD9 — WITHDRAWN at rev 2

Revision 1 proposed that, after a buffer-first removal, a filesystem failure would leave the buffer unrestored. Q#RD2's phase ordering makes the situation unreachable: nothing is removed before the filesystem mutation succeeds, so there is no lost buffer to restore. The decision number is retained rather than reused, so review can see it went away rather than being renumbered.

4. Bets (falsifiable)

B1 — Refusing breaks no legitimate server workflow. A server deleting a file the user has unsaved edits in is a conflict the user must resolve. Falsified by a real server whose normal operation deletes files the user is actively editing.
B2 — Mid-batch refusal is acceptable because the protocol already specifies it. §1.7's Abort semantics are the spec's own answer for resource-op-bearing edits. Falsified if a server is found that requires transactional application and degrades badly under Abort. Acceptance 12 pins the observable behaviour either way.
B3 — Prefix-aware validation does not over-refuse. Falsified if a common workflow deletes a directory while an unrelated modified buffer sits beneath it and the refusal is judged unhelpful.
B4 — Leaving clean descendants orphaned is the lesser evil (Q#RD5). Falsified if orphaned clean buffers after a recursive delete prove more disruptive than the tree-wide lifecycle defect that removing them would create.

5. Acceptance

Each criterion states the pre-image it must fail against. A test that passes against its pre-image has no bite and is rejected.

A delete op targeting a modified buffer refuses, and the file survives. Assert together: the call fails, the buffer is still in the registry with its exact unsaved text, and path.exists() is still true. Bite: fails against ad41cf1 unmodified. Asserting only that the buffer survived is vacuous — that is mode (c)'s existing behaviour. The exists() assertion carries the bite.
A delete op targeting a clean open buffer still succeeds, file removed and buffer removed. Bite: fails against an over-broad guard that refuses whenever a buffer is open. Assert both directions.
A filesystem failure preserves the clean buffer (Q#RD2). Force the fs mutation to fail (e.g. a non-empty directory without recursive) and assert the buffer is still present and intact. Bite: fails against revision 1's buffer-first ordering, which would have removed the buffer and then failed.
on_removed observes the path absent (Q#RD2). Register an on_removed callback that stats the path and records the result; assert it saw the path already gone. Bite: fails against revision 1's buffer-first ordering, under which the callback would observe the file still present. This is the pin that keeps the phase order from silently regressing.
A delete called from inside the target's own edit intercept refuses before disk (Q#RD2). Assert the file still exists. Bite: fails against ad41cf1, where ConcurrentEdit is discovered only at removal time — after remove_file has already run.
Duplicate path-bound buffers cannot hide a modified copy (Q#RD6). Create two buffers on one path via pmacs.buffer.from_file, leave the first clean and modify the second, then delete. Bite: fails against any first-match lookup, including EditorCore::find_buffer_for_path — which is exactly what revision 1 specified.
Component-prefix false positives are rejected (Q#RD6). A modified buffer under /tree-sibling must not block a recursive delete of /tree. Bite: fails against a string-prefix implementation. Pairs with criterion 8 so both directions of the prefix rule are pinned.
recursive = true over a directory containing a modified buffer's file refuses, and the whole tree survives (Q#RD5). Assert the inner file still exists — not merely that the buffer does, which is already true today (mode (c)). Bite: fails against exact-path-equality validation.
A clean recursive delete leaves descendant buffers orphaned, not removed (Q#RD5). Assert the descendant buffer is still in the registry after a successful recursive delete. Bite: fails against an implementation that widens reconciliation to the tree. This pin exists specifically to stop the parked defect from being enlarged, and it is expected to look odd — it asserts today's imperfect behaviour deliberately.
ignore_if_not_exists = true on an absent path leaves a modified buffer intact (Q#RD4), reproducing mode (b): file removed behind pmacs's back first, then the op. Bite: fails against a fix guarding only the branch where the fs delete actually ran.
Absent-plus-ignore succeeds through the real server pump (Q#RD4, layer 2). Drive it end to end and assert the batch is not refused and the server is told applied = true. Bite: fails against a preflight that rejects on the presence of a modified buffer without consulting ignore_if_not_exists — the false-positive Q#RD4 exists to prevent.
Edit-then-delete and rename-into-delete still answer the server (Q#RD3, Q#RD7). Two batches that defeat the snapshot preflight: one where an earlier text edit dirties the buffer a later op deletes, one where an earlier rename moves a modified buffer into a later delete's subtree. Assert in both cases that the server receives applied = false with a non-empty failureReason. Bite: fails against ad41cf1 (the raise is swallowed at lsp.lua:1892 and no response is sent) and against a preflight-only fix that claims atomicity — these are the cases revision 1's atomicity claim asserted could not happen.
The refusal reaches the server on the unattended path, and the user-initiated paths report on the status line naming the buffer. Bite: fails against a fix that refuses by raising. A direct-call test on apply_resource_op does not satisfy this and is rejected as insufficient — the guard must be pinned through the outermost user-reachable seam.
m4_15_workspace_edit_resource_ops_apply_in_order stays green unmodified, pinning no-regression from outside. Its c.rs is never opened, so it exercises exactly the unguarded case that must keep working (Q#RD6).
Every new test is checked with scripts/bite and none reports VACUOUS.

6. Parked — not deferred-and-forgotten

Mode (d): the dangling window and the emptiable registry (§1.1, Q#RD8). Needs its own lane and a census, because the two removal paths clean disjoint sets and the obvious unification regresses four cleanups. Q#RD5 is written to avoid enlarging it.
kill_buffer and editor.quit have the same gap (§1.4). editor.before-quit exists as a veto channel with no subscriber. This lane sets the precedent; those are separate lanes.
Declaring workspace.workspaceEdit capabilities — documentChanges, resourceOperations, failureHandling (§1.11). Declaring them changes what servers send, so it needs its own evidence and its own lane.
pmacs.error is undefined (§1.5) — 11 dead call sites in builtin/, including the one that is supposed to surface every uncaught async coroutine error. A known standing defect, widened in relevance by this framing but not fixed by it.
A y_or_n helper, minibuffer queuing, and a held-server-request ledger — the three prerequisites that would make §2.2 cheap rather than merely expensive.
lsp.confirm-server-edits, the config-registry adopter that would let a user loosen Q#RD1 once a prompt mechanism exists.
The rename side of prefix-aware, normalizing lookup — dired Stage 2's, per Q#RD5.

7. Gates

Full suite per CLAUDE.md: cargo fmt --check; cargo clippy --workspace --all-targets -- -D warnings as its own step; cargo test --lib; cargo test --lib --features crdt; the touched acceptance suites; cargo test --test m4_acceptance -- --skip basedpyright; PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu; git diff --check.

Touched suites: m4_acceptance (the resource-op home, §1.14) and lsp_dispatch_seams_acceptance. dired_acceptance and autosave_acceptance are watch items — the former for Q#RD6's shared lookup, the latter because on_removed ordering (acceptance 4) is where autosave's discard_buffer hangs.

Gate the pushed tree, not the worktree — commit first, then gate.

While the document is still PROPOSED the gate is git diff --check plus a docs read; the full suite runs once implementation lands on this branch.

8. Branch plan

resource-op-delete-guard, worktree ../pmacs-resource-op-delete, one branch, one PR — #186, which becomes the implementation PR. Revision 2 withdraws revision 1's two-PR plan, which conflicted with one-feature/one-branch/one-PR: the framing is revised in place, and once approved the implementation commits land on this same branch.

Implementation does not begin until the user approves this revision.

Files the implementation will touch: src/lua_bindings/mod.rs (the delete arm's four phases and the shared all-buffers query), builtin/runtime/lsp.lua (the conflict check, per-op wrapping, origin restore, always-answer), tests/m4_acceptance.rs and src/bin/pmacs_fake_lsp.rs (fake modes for the blocked delete, the edit-then-delete and rename-into-delete batches, and absent-plus-ignore). It will not touch src/daemon.rs, pmacs-protocol/, builtin/runtime/dired.lua, docs/agent-handoff.md or COHERENCE.md. No protocol change.

Ownership note. docs/active-work.md records that dired Stage 2a — "rename/delete reconciliation substrate" — overlaps builtin/runtime/lsp.lua and warns against running it concurrently with other work touching those files "without assigning those files to one lane first". This lane claims the delete half of that substrate and builtin/runtime/lsp.lua's applier for its duration; the lane entry in docs/active-work.md records the claim.

47 KiB Raw Blame History

Framing — apply_resource_op delete destroys unsaved work