Skip to content

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

TypeScript

Delete work-tracker/specs/gfs-authority-grants-shares-move-r4.md

Miguelitod12f79792e63
diff --git a/work-tracker/specs/gfs-authority-grants-shares-move-r4.md b/work-tracker/specs/gfs-authority-grants-shares-move-r4.md
deleted file mode 100644
index 0ddc792fb..000000000
--- a/work-tracker/specs/gfs-authority-grants-shares-move-r4.md
+++ /dev/null
@@ -1,117 +0,0 @@
-# GFS Desktop — authority lifecycle, grants/shares independence, Move pagination (R4 spec)
-
-Status: implemented (R4 fix round)
-Scope: `desktop-app/ui` — `useGfsBrowserController`, `FilesPage`, `GfsGrantList`, `GfsMoveDialog`
-Supercedes: the ad-hoc corrective patches from the R3 fix round (`93f211d08`). This document
-is the durable contract for the three behavior areas below; future changes to these files
-must keep this spec true or update it in the same commit.
-
-## 1. GFS authority / cache / error lifecycle
-
-### Roles
-
-- **Server is the only authority.** Permissions (affordances), listings, grants, shares,
- and versions (`ifMatch`) are always server responses. No client cache may be treated as
- an authorization fact.
-- **Discovery (`listAccessible`) is the session/authority boundary.** It is
- permission-derived session state, so on every controller mount it is revalidated
- (`refetchOnMount: 'always'`) even though the production client otherwise never
- refetches (`staleTime: Infinity`, `refetchOnMount: false`).
-- **`accessState`** (`'active' | 'revoked'`) is session-local UI state owned by the
- controller. `'revoked'` gates every GFS query observer (`enabled`) and is the only
- fail-closed verdict; `retryAccess()` merely re-enables the queries — a fresh server
- success is the only way data returns.
-
-### What the UI may render while authority is being revalidated
-
-- `authorityPending` is true from controller mount (or session-scope return) until the
- first fresh discovery response lands (success or failure), whenever discovery is
- available in the runtime.
-- While `authorityPending`, the controller withholds all cached GFS state it exposes:
- `accessibleResources`, `items`, `affordances`, `rowAffordances`, `grants`, and `shares`
- are reported as empty/`null`. FilesPage renders the loading state, never cached rows.
- Prefetched children therefore cannot bypass revalidation: their cache may exist, but it
- is not rendered until discovery re-proves the session.
-- Local navigation chrome (breadcrumb trail titles typed by the user's own navigation)
- is not server-derived data and may remain; it is cleared on failure (below).
-
-### Which queries/caches are cleared on authority failure
-
-- Every session-scoped GFS query is removed via `queryClient.removeQueries({ queryKey:
-desktopQueryKeys.gfsRoot })` — accessible roots, folder children (including prefetch),
- affordances (dialog + row), grants, and shares. The Move dialog deliberately shares
- these exact keys, so its destination listings are purged too.
-- Removal (not invalidation) is required: under production defaults an invalidated-but-
- cached query would keep rendering its stale data.
-
-### Which local UI state is cleared on authority failure
-
-- Controller: `crumbs`, `openError` (`clearGfsState`), and `accessState → 'revoked'`.
-- FilesPage (via effect on `accessState === 'revoked'`): file preview state (dialog +
- already-fetched bytes), Manage dialog, Move dialog target, rename dialog target +
- inline rename form, delete confirm, open-link dialog, and the inline create-folder form.
- Anything that could display or act on stale GFS data must close.
-
-### How 401 / typed authority failures reach one boundary
-
-- One classifier: `isGfsSessionAuthorityFailure(message, surface)`.
- - `surface: 'discovery'` — 401 **or** 403/unauthorized/forbidden fail closed (the
- discovery listing itself is permission-derived).
- - `surface: 'operation'` — only a bare 401 / "not authenticated" / "unauthenticated"
- or a typed lifecycle code (`desktop_user_retired`, `operator_link_inactive`,
- `operator_link_invalid`, `gfs_operator_link_invalid`) fails closed. A generic 403 on
- one resource is a policy verdict (e.g. `manage_acl_required`, `escalation_rejected`)
- and stays local to that operation.
-- **Query path**: errors from accessible, children, affordances, row-affordances,
- grants, and shares queries are collected and routed into the same boundary effect.
-- **Imperative path**: `handleAuthorityFailure` is wired into `openUri`, every
- controller mutation (`onError`), and every FilesPage imperative catch (grant, revoke
- grant/share, create share, create folder, upload, replace, rename, delete, move,
- download) plus preview byte-fetch failures (`onDownloadError`). A Move commit failure
- first passes the boundary: an authority failure closes the dialog and fails the
- session; anything else remains the dialog's in-place banner (403/412 policy verdicts).
-
-### Cached data under production `staleTime: Infinity`
-
-- Cache is a rendering optimization only. It may be served while `active` and not
- `authorityPending`, must be withheld during authority revalidation, and is deleted on
- any authority failure. Content mutations refresh listings through explicit
- invalidation; permission affordances are refreshed when Manage opens or a row menu
- resolves.
-
-## 2. Grants / shares partial-failure independence
-
-- `listGrants` and `listShares` are independent surfaces with independent failure modes.
-- `GfsGrantList` renders grant rows and share rows as independent sections:
- - A grants-list error shows the grants banner (quiet for `manage_acl_required`) and
- suppresses grant rows only; share rows and their revoke actions still render.
- - A shares-list error shows the shares banner and suppresses share rows only; grant
- rows and their revoke actions still render.
- - The combined "Loading access…"/empty notices appear only when neither list errored.
-- Neither source's failure may hide, disable, or suppress the other's rows or actions.
-
-## 3. Paginated Move destination navigation
-
-- The Move dialog browses the same session-scoped caches as the Files page
- (`gfsAccessible` at the root, `gfsChildren` inside folders).
-- Both listings are cursor-paginated. Whenever the active listing reports a next page,
- a "Load more" control is visible; fetching the next page preserves the rows already
- rendered, shows pending state on the control, and surfaces fetch errors through the
- dialog's existing error banner.
-- Destinations loaded from any page are selectable identically to page-one rows.
-- Cycle prevention is unchanged: the moved resource itself never appears as a
- destination, and "Move here" stays disabled while the dialog path passes through the
- target's own subtree; a server 403/412 remains an in-dialog banner.
-
-## Regression coverage map
-
-| Decision | Tests |
-| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| Withhold cache during authority revalidation; purge + revoke on 401 (production query defaults) | `useGfsBrowserController.test.tsx` — "withholds cached GFS state … until discovery revalidates" / "fails closed … drops cached gfs state" |
-| Query + imperative + preview paths reach one boundary | `useGfsBrowserController.test.tsx` (mutation 401), `FilesPage.test.tsx` ("fails closed and closes previews/dialogs when authority is revoked") |
-| FilesPage local UI cleared on revocation | `FilesPage.test.tsx` — previews/manage/move/rename/delete state |
-| Grants/shares independence | `GfsGrantList.test.tsx` — "a share-list failure does not hide grants" |
-| Move pagination + page-two selection | `moveDialog.test.tsx` — root and child two-page listings |
-
-Previous-buggy-head evidence: all new tests above fail on `93f211d08` (recorded in the R4
-fix commit message).