Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs(design): add GFS move-forbidden UX matrix and breadcrumb drop-move plan

Miguelon Peluchon966a3d6473c7
diff --git a/docs/design/gfs-breadcrumb-drop-move.md b/docs/design/gfs-breadcrumb-drop-move.md
new file mode 100644
index 000000000..bd9c48603
--- /dev/null
+++ b/docs/design/gfs-breadcrumb-drop-move.md
@@ -0,0 +1,127 @@
+# Breadcrumb drop-move — implementation plan (Control UI, Desktop parity phase 2)
+
+**Sibling doc:** [`gfs-move-forbidden-ux-matrix.md`](./gfs-move-forbidden-ux-matrix.md) —
+the deny-reason → message/visual matrix. This feature MUST reuse those treatments for
+refused breadcrumb drops.
+
+**HARD CONSTRAINT — NO BACKEND CHANGES.** The move PATCH, permission model, and policy
+server contracts are frozen. Everything here is browser/renderer-side. Allowed areas:
+`control-ui/**`, `desktop-app/ui/**` (phase 2), and only surface-agnostic pure additions
+to `packages/gfs-interaction-policy` if genuinely needed. Do **not** touch
+`control-api`, `external-rest-api`, `gfs-controller`, `deploy/`, or any DB.
+
+---
+
+## 1. Feature
+
+Users drag a file **or folder** from the listing onto a **breadcrumb crumb** — an
+ancestor folder (e.g. `Product` while browsing `main › Product › live tests`) or the
+drive root (`main`) — to move it there. Today the only upward-move path is the row ⋯
+menu → Move dialog. Crumbs are plain buttons (`GfsBrowser.tsx`,
+`cu-gfs-breadcrumb__button`) with no drag handlers, while rows already advertise
+draggability ("Drag {name} into a folder to move it", `GfsBrowser.tsx:2372`).
+
+## 2. Current state (receipts)
+
+| Fact | Where |
+|---|---|
+| Breadcrumb = `<nav aria-label="Breadcrumb">` of per-crumb `<button>`s; click = `goToCrumb(index)`; active crumb carries `aria-current="page"`; only active crumb has ⋯ menu | `control-ui/components/GfsBrowser.tsx` (~line 2255) |
+| Crumb model: `{ id, rid, gfsUri, name, version, isDriveRoot }`; drive root is synthetic (`id === null`) — `isDriveRootCrumb` | `GfsBrowser.tsx:141-149` |
+| Rows: `draggable`, native tooltip, per-row `onDrop` + container `onDrop` → `handleGfsDrop` | `GfsBrowser.tsx:2217, 2372, 2389` |
+| Shared, browser-safe move policy (structure + authority + convergence) already consumed by both UIs | `packages/gfs-interaction-policy/dragPolicy.cjs` |
+| One-confirmation move flow with numbered-name toggle + impact copy | `control-ui/components/GfsMoveConfirmDialog/index.tsx`, `GfsMoveDialog/index.tsx` |
+| Commit runner re-resolves source, sends version, bounded 409 ladder, honest unknown-outcome handling | `desktop-app/ui/src/gfs/moveCommit.ts` pattern; Control UI equivalent in its drop commit path |
+
+## 3. Design
+
+### 3.1 Drop targets
+- **Every crumb** becomes a drop target: all ancestor crumbs **and the drive-root
+ crumb** (`main`). The **active crumb** is also a target but always resolves to
+ `same-parent` (policy `dragPolicy.cjs:84/118`) → info-level "already here" (matrix
+ doc §3 A4), never error styling.
+- Root crumb (`id === null`): root can never be inside the source's subtree, so the
+ structural decision is trivially safe; treat as a normal directory target whose
+ identity is the drive root. Authority: use the drive-root affordances if the session
+ exposes them; in the admin plane the operator is intrinsic (all bits) so the drop
+ proceeds. For non-operator desktop parity (phase 2), admit the drop and let the
+ server be the authority (`server-check-required` semantics) — never fake a deny.
+
+### 3.2 Reuse the existing drag pipeline (do not fork it)
+- Crumbs join the **same drag session**: `dragstart` on rows already publishes source
+ facts; crumbs register as targets with `dragover` (preventDefault + verdict request),
+ `dragleave`, `drop`.
+- Hover: request the same adjudication (`hoverVerdict`) — shared cold-hover budget,
+ cached/canceled checks cost nothing; verdict states `checking │ allowed │ denied │
+ unavailable` painted on the crumb via `data-drop-state` (+ `data-drop-reason` per the
+ matrix doc's implementation notes).
+- Drop: same drop-time adjudication (priority check; ownership epoch captured; stale
+ gestures cannot commit). Then the **same** confirm dialog + commit runner as row
+ drops — one confirmation, numbered-name suggestion on conflict.
+
+### 3.3 Visual + copy
+- Allowed crumb: blue tint (same treatment as `allowed` rows). Denied crumb: never
+ blue; on refused drop surface the reason message from the matrix doc (§3 A1–A12) —
+ toast, correct tone (error / info for `same-parent` / warning for `unavailable`).
+- SR: announce verdict with reason on the crumb (same one-wording-per-reason contract
+ as RP-026; Control UI equivalent of `gfsDropVerdictAnnouncement`).
+- Keep the native row tooltip; optionally extend it: "Drag {name} into a folder or the
+ breadcrumb to move it".
+
+### 3.4 Races and gotchas (each already bit this PR once)
+- **Crumb click vs drop:** `dragover` must `preventDefault()`; `drop` must
+ `preventDefault()` + `stopPropagation()` so the container-level `onDrop`
+ (`GfsBrowser.tsx:2217`) doesn't double-handle; clicks don't fire after a drop, but
+ verify no navigation happens on `mouseup` during drag.
+- **Breadcrumb reconstruction race (R7-M1):** capture the crumb's identity
+ (`id`/`rid`/`gfsUri`/`version`) at drop time, not the live trail; a late trail
+ rebuild must not re-anchor an in-flight commit. The commit runner's pre-dispatch
+ re-resolve must resolve the **target** too, not only the source.
+- **Ownership epochs:** dropping on a crumb is a normal drop — the same gesture-epoch
+ guard applies (a newer gesture supersedes stale work; dragend must not cancel the
+ drop's own adjudication).
+- **After commit:** reuse `planMoveConvergence` (old + new parent child-listing
+ refetch). The user stays in the current folder; the moved item disappears from the
+ listing. No auto-navigation.
+
+## 4. Files to touch (allowlist)
+
+| Area | Change |
+|---|---|
+| `control-ui/components/GfsBrowser.tsx` | crumb drag handlers, verdict state per crumb, drop wiring into existing commit path |
+| `control-ui/app/globals.css` | `cu-gfs-breadcrumb__button` drop-state styles (`checking/allowed/denied/unavailable` + reason attribute) |
+| `control-ui/e2e/run-gfs-drag-and-drop.mjs` + component tests | cases below |
+| `packages/gfs-interaction-policy` | ONLY if a pure helper (e.g. root-target facts) is genuinely needed; no signature breaks |
+| Phase 2: `desktop-app/ui/src/pages/FilesPage.tsx` + `styles.css` | Desktop Files breadcrumb parity (`aria-label="Breadcrumb"` exists there today) |
+
+## 5. Test plan
+
+- ☐ Drag `abac.md` onto `Product` crumb → confirm dialog shows "Move abac.md to
+ Product?" → commit → listing refreshes; file gone from `live tests`, present in
+ `Product`.
+- ☐ Drag onto drive-root crumb `main` → moves to root (admin plane).
+- ☐ Drag onto the ACTIVE crumb → info "already here", no error styling, no PATCH.
+- ☐ Folder onto ancestor crumb (incl. a crumb above its own parent) → moves;
+ descendant targets are impossible by construction (crumbs are ancestors) — assert no
+ `descendant` case can trigger here.
+- ☐ Denied reasons per matrix doc: `destination-write` / `source-write` / /
+ `source-delete` → crumb not blue, refused drop shows the reason message + SR
+ announcement.
+- ☐ Hover budget exhausted → crumb shows `unavailable`; drop still runs the drop-time
+ check.
+- ☐ Breadcrumb reconstruction mid-drag → drop commits against captured crumb identity;
+ no mis-anchored trail (R5-M1/R7-M1 regression suite stays green).
+- ☐ Keyboard/access: crumb buttons keep click-navigation; Move dialog unchanged as the
+ keyboard path; verdicts announced via aria-live.
+- ☐ Control UI production build + permission suites green; Desktop untouched in
+ phase 1.
+
+## 6. Acceptance criteria
+
+1. From any listing row, a file or folder can be moved to any visible ancestor crumb
+ (including root) with one confirmation — no ⋯ menu needed.
+2. Every refused crumb drop explains WHY in plain language (matrix doc), visually and
+ to SRs; nothing is silently ignored.
+3. Zero changes outside the allowlist in §4; backend untouched (verifiable via
+ `git diff --stat`).
+4. All existing drag-and-drop suites (unit, component, property, Playwright spec)
+ remain green; new cases in §5 pass.
diff --git a/docs/design/gfs-move-forbidden-ux-matrix.md b/docs/design/gfs-move-forbidden-ux-matrix.md
new file mode 100644
index 000000000..40327249e
--- /dev/null
+++ b/docs/design/gfs-move-forbidden-ux-matrix.md
@@ -0,0 +1,135 @@
+# EvenDrive move-forbidden UX — full case matrix
+
+**Worktree:** `feat/even-drive-drag-and-drop-fix` · **Scope:** Desktop sidebar tree + Files
+panel (Control UI parity noted where it differs)
+**Sibling doc:** [`gfs-breadcrumb-drop-move.md`](./gfs-breadcrumb-drop-move.md) — breadcrumb drop targets; refused drops there MUST use this matrix for messaging.
+**Goal:** every forbidden-move case tells the user WHAT happened and WHY — visually and
+programmatically — instead of the current silent refusal.
+
+---
+
+## 1. Why it is silent today (receipts)
+
+The deny **reason is computed and then thrown away** at the UI layer:
+
+| Layer | File | What it does |
+|---|---|---|
+| Structure decision | `packages/gfs-interaction-policy/dragPolicy.cjs` → `decideDragStructure` | returns `{kind:'deny', reason:'self'│'cross-drive'│'root-source'│'same-parent'│'descendant'}` or `server-check-required` |
+| Authority decision | `dragPolicy.cjs` → `decideDragAuthority` | returns `{kind:'deny', reason:'destination-write'│'source-write'│'source-delete'}`, `checking`, `unavailable`, `observed-allowed` |
+| Adjudication | `desktop-app/ui/src/gfs/dragAdjudication.ts` | maps probes/session loss to `session-lost`, `unavailable`, `target-unavailable`, `source-location-unknown` |
+| Paint | `FileExplorerTree/index.tsx:314` | row gets `data-drop-state={allowed│denied│checking│unavailable}` — **reason collapsed to a boolean-ish state** |
+| Speech | `dropVerdict.ts` (RP-026) | generic only: *"You cannot move into {target}."* — no reason |
+| CSS | `styles.css:1987-2010` | **Tree:** `denied` only de-emphasizes the label (1999) — nearly invisible. **Files grid:** `checking`/`allowed` styles exist; **`denied` has NO style at all** → this is the "no blue highlight and no idea why" bug |
+
+**The two symptoms you hit are exactly this:**
+- Sidebar tree: `denied` ≈ invisible (label dimming only) → "nothing happens".
+- Files panel: `allowed` paints the blue highlight; `denied` has no CSS → no highlight,
+ no explanation.
+
+Design rule already in the codebase (RP-026 header comment): *paint the verdict on the
+row for sighted users, speak it for SR users*. The fix keeps that shape but carries the
+**reason** through and adds a **persistent, readable explanation at drop time** (row
+tints alone are too subtle to read a reason from).
+
+---
+
+## 2. The two-phase gate (when is a move forbidden?)
+
+A move must pass BOTH phases. The reason shown must name the phase.
+
+**Phase A — drag adjudication (before confirm):** structure check → authority check
+(`decideDragAuthority`: needs `write` + `delete` on the **physical source parent** and
+`write` on the destination; bits may be direct/inherited/team).
+**Phase B — commit (after confirm):** server re-validates atomically (cycle/self guard,
+destination kind, parent permissions) and executes the PATCH (with numbered-name ladder
+on 409).
+
+> Verified live example (dev cluster, 2026-10-23): dragging `live tests` → `Assets`
+> fails Phase A with `source-write`/`source-delete` because `live tests`' physical
+> parent is a nameless folder where the desktop user holds **zero** bits — even though
+> the user holds ALL bits on both `live tests` and `Assets` themselves. `gfs_audit`
+> shows **no mutation rows** → refused client-side, silently.
+
+---
+
+## 3. Phase-A matrix — every drag-time forbidden case
+
+| # | Reason (code) | Trigger — what the user did | Underlying rule | Sidebar tree feedback | Files panel feedback | Persistent message (drop) | SR announcement |
+|---|---|---|---|---|---|---|---|
+| A1 | `self` | Drop onto the dragged item itself | `dragPolicy.cjs:73` | row `denied` + tooltip | row `denied` | Banner/toast: "You dropped {name} onto itself. Pick a destination folder." | "You cannot move {name} into itself." |
+| A2 | `cross-drive` | Drop across drives | `dragPolicy.cjs:76` | same as A1 | same | "Moving between drives isn't supported." | same, spoken |
+| A3 | `root-source` | Source is the drive root (or virtual root item that is physically root) | `dragPolicy.cjs:79` | refused at dragstart: don't start a session, or show `denied` on all targets | same | "This location is the top level — it can't be moved." | spoken |
+| A4 | `same-parent` | Target IS the physical parent (no-op move) | `dragPolicy.cjs:84` + path form `:118` | row `denied` | row `denied` | "{name} is already in {target}." — **NOT an error tone; info**. Critical with the flat sidebar: e.g. `Assets` physically lives in `Product`, so dragging Assets→Product is a no-op even though it *looks* like a real move | "{name} is already in {target}." |
+| A5 | `descendant` | Folder dropped into its own subtree | `dragPolicy.cjs:92` | row `denied` on the whole subtree | highlight suppressed | "You can't move {name} into a folder inside itself." | spoken |
+| A6 | `destination-write` | No `write` on destination (e.g. read-only share) | `dragPolicy.cjs:146` — checked FIRST (surface the user acts on) | row `denied` — this is the case where the blue highlight must NOT appear | row `denied`, no blue | "You don't have permission to move items into {target}. You need edit access to the destination folder." | spoken with reason |
+| A7 | `source-write` | No `write` on the physical **source parent** | `dragPolicy.cjs:147` | row `denied` | row `denied`, no blue | "You can move {name} within places you manage, but not out of its current folder — you don't have edit access to the folder that contains it." | spoken |
+| A8 | `source-delete` | `write` but no `delete` on the source parent | `dragPolicy.cjs:148` | row `denied` | row `denied`, no blue | "Removing {name} from its current folder needs delete access there. You have edit, but not delete." | spoken |
+| A9 | `checking` | Bits not yet known (cold hover) | `dragPolicy.cjs:140` | neutral spinner-tint row | neutral | none (transient) | "Checking whether you can move into {target}…" |
+| A10 | `unavailable` / `target-unavailable` / `source-location-unknown` | Probe failed (network/5xx); hover budget exhausted | `dragAdjudication.ts:58-98` | row `unavailable` — must NOT look denied | row `unavailable` | "EvenDrive couldn't verify the move just now. Check your connection and try again — the move is still allowed on drop." (drop-time check remains available by contract) | spoken |
+| A11 | `session-lost` | 401 during probe | `dragAdjudication.ts:58` | gesture ends; re-auth prompt | same | "Your session ended. Sign in again to continue moving files." (session revoked per med-probe-401) | spoken |
+| A12 | `server-check-required` | Ancestry unproved (grants start below root) | `dragPolicy.cjs:121` | row `checking` — NOT denied; stays landable | neutral | none at hover; drop proceeds to server verdict (Phase B) | "Checking…" |
+
+---
+
+## 4. Phase-B matrix — commit-time outcomes (after "Move" confirm)
+
+Source of truth: `moveCommit.ts` `presentMoveCommitOutcome` (rev-2 §8 toasts) +
+`dragAdjudication.ts` verdict reasons.
+
+| # | Outcome | Trigger | Message (toast) | Tone |
+|---|---|---|---|---|
+| B1 | `committed` (+ optional `renamedTo`) | PATCH 200 | "Moved {source} to {destination}." / "…as {renamed}." | success |
+| B2 | numbered-name conflict resolved | 409 → ladder accepted | same as B1 with "as {renamed}" | success |
+| B3 | conflict ladder exhausted | 409 × N > limit | "A name collision couldn't be resolved for {source} in {destination}. Try renaming first." | error |
+| B4 | source vanished (404 on source re-resolve/dispatch) | rp-027 | "{source} no longer exists — it may have been deleted or moved by someone else." | error |
+| B5 | destination vanished (404 on destination) | rp-027 | "The destination folder no longer exists." | error |
+| B6 | server structural deny (cycle/kind/parent-permission re-check) | PATCH 403/400 | distinct copy per status; if parent-permission: same wording as A7/A8 + "the change was not made" | error |
+| B7 | transport loss, outcome unknown | fetch threw after dispatch | "The connection dropped while moving {source}. EvenDrive is checking whether the move completed…" then verify-by-identity → converge to B1 or "couldn't confirm; refresh Files" | warning→info |
+| B8 | 5xx | server error | "EvenDrive couldn't complete the move. Nothing was changed. Try again." | error |
+| B9 | `session-lost` | 401 at commit | "Your session ended. Sign in again — the move was not completed." | error |
+| B10 | user stopped / canceled dialog | Stop / Esc / backdrop | silent or "Move canceled." (per PR's stop-notice pattern) | info |
+
+---
+
+## 5. Visual spec (what to change)
+
+1. **Carry the reason**: extend `GfsDropVerdict` (dragSession.types) with `reason`;
+ `data-drop-reason` attribute next to `data-drop-state` (FileExplorerTree:314, grid
+ rows). Tests in `dropVerdict`/RP-026 keep their one-wording-per-verdict contract by
+ keying on reason, not surface.
+2. **Give `denied` a real treatment in BOTH surfaces** (today: tree = label dim only,
+ grid = nothing):
+ - Tree row + grid row: red/neutral border tint (match existing `allowed` blue
+ treatment, not-blue), reduced-opacity drag ghost.
+ - **Do NOT** use error-red for `same-parent` (A4: info) or `unavailable` (A10:
+ warning) — reasons map to tones: deny=error, no-op=info, unknown=warning.
+3. **Drop-time persistent message**: on a refused DROP, show the reason message from
+ the matrix as a toast (reuse `pushToast` from `presentMoveCommitOutcome`) or the
+ `StatusBanner` component — banners for `session-lost` (persistent), toasts for
+ one-shot denies. Hover-time stays row-tint-only (no toast spam while dragging over
+ many rows).
+4. **SR**: extend `gfsDropVerdictAnnouncement(state, target)` →
+ `(state, target, reason)`; on drop, announce the full reason sentence (RP-026
+ contract: same wording per reason on every surface).
+5. **Blue highlight rule stays**: only `observed-allowed` (and `checking`→neutral)
+ paints blue. The fix is not to show blue more — it's to SAY WHY when it isn't blue.
+
+## 6. Plain-language copy rules (match PR's existing tooltip style)
+
+- Name the **missing access**, not the bit: "edit access" = write, "delete access" =
+ delete. Never "source-parent-write".
+- Distinguish the **three places** a move touches: the item, the folder it leaves, the
+ folder it enters. A7/A8 messages must mention "the folder that contains it".
+- No-op moves (A4) get info tone + "already there", never "cannot".
+- Unknown (A10) never implies forbidden — say "couldn't verify, try again".
+
+## 7. Manual test matrix (maps to your PR checklist lane 1/3)
+
+- ☐ A4 drag `Assets` onto `Product` (physically already inside) → info "already there", NOT red
+- ☐ A7 drag `live tests` onto any folder → refused drop + banner naming "the folder that contains it"
+- ☐ A6 read-only destination share → no blue, reason names destination
+- ☐ A5 folder into own subfolder → refusal names self-containment
+- ☐ A10 kill network mid-hover → warning tone, drop still attempts
+- ☐ B4/B5 vanish source/destination via second user → distinct messages
+- ☐ B7 drop during network cut → "checking whether it completed", then converge
+- ☐ SR: every refused drop announces reason; sighted: every denied row readable