[zach88]

What

Completes the server side of the GFS watch: authorization and session changes are pushed to open streams, and the per-user 4-second entity-change stream is retired. Control-api and ERA, plus test updates in control-ui.

1. Change notifications for authorization and session (migrations 0140 to 0145, one per table):
   • gfs_authz_changed: one pg_notify per key on gfs_grants, gfs_shares, gfs_desktop_operator_links, control_admin_users and team_members. Subject keys carry the id only for user/team subjects of uuid length.
   • gfs_watch_session: users UPDATE (when the lifecycle changed) and DELETE.
   • The migration runner retries a lost lock wait (55P03) for migrations that declare lockRetries (validated to 0..3); only team_members and users do.
   • Total parsers parseAuthzKey and parseSessionHint.
2. Reauthorize on authorization changes:
   • A 250 ms window collects direct user keys and expands team and admin keys with one query per kind on the watch pool, filtered against live connections at flush time.
   • A failed expansion is retried once. A second failure, an unreadable or throwing hint, or more than 10,000 ids in one window fails closed: every connected user is held at once and reauthorized, at most once every 5 s per replica, with the closes spread.
   • A move or soft delete of an ancestor reauthorizes user connections whose accepted keys sit on that chain. Linked operators keep their access.
3. Root listings and session:
   • A change visible in a root listing sends roots_changed {} to connected users with read through a direct or team grant (one query per 250 ms window) and to every linked operator, at most once every 2 s per connection with a trailing notice. Inserts skip the grantee query. A held connection never receives it.
   • Each gfs_watch_session NOTIFY is a hint: the affected user is held, the window confirms against users in one query, and closes with session_expired only when the row is gone, retired or carries another lifecycle_version. A failed or unreadable confirmation closes with reauthorize. A forged hint over an active row closes nothing.
   • Listener loss and shutdown cancel every window and release every hold.
4. Retire the per-user entity-change stream:
   • control-api: /external/entity-changes/stream, its per-user open limiter and entityChangeUserVisibilityRefreshMs are removed. streamEntityChanges becomes operator-only. The operator stream (/gfs/entity-changes/stream) keeps its limiters, admin auth and periodic recheck.
   • external-rest-api: /entity-changes/stream is removed.

Why

The per-user stream is a security fix that became the refresh mechanism: it sends a generic invalidation every 4 seconds by default with no ids, plus a session check per tick, so users are isolated from the timing of the global feed. With the watch carrying per-resource changes, revocations and session changes, that stream has no remaining job, and keeping it would leave two paths with different guarantees.

How

• One migration per table keeps each transaction to a single table lock, so applying them cannot deadlock against an application writer that touches two of these tables.
• Revocation never waits on a successful query: every failure path ends in reauthorize, which makes the client reopen and re-authorize from scratch. Holds are released only by iterating their own structure.
• A session hint is never trusted on its own; it is confirmed against users before any session_expired.

Testing

All server suites run against real Postgres with the real triggers and writers.

• gfsWatch.authzSessionTriggers.realPostgres: one NOTIFY per key for every writer of every table, payload parsing, trigger WHEN conditions.
• gfsWatch.authzWindow.realPostgres: expansion per kind, retry, fail-closed (second failure, unreadable hint, id ceiling) with its rate limit, ancestor chain revocation, linked operators.
• gfsWatch.rootsSession.realPostgres: root notices, their rate limit and trailing notice, session confirmation outcomes, forged hints.
• Model-based: gfsWatch.authz.property.realPostgres and gfsWatch.rootsSession.property.realPostgres (fast-check commands and scheduler against a reference model). The registry property test now checks the read and kind of every decision on every connection, closed streams included, and anchors the suspicion window at the op's real start.
• migrationExecutionPolicy: lockRetries validation and the retry on 55P03.
• entityChangeStreamRetirement.realPostgres and routes.entityChangesRetired (ERA): both retired routes answer 404 and the operator stream stays live.
• externalSessionCurrentness.realPostgres rewritten against the session observer and the watch.
• At this head: tsc --noEmit clean; npm test 635 files / 8961 tests passed (real-Postgres suites skip in this lane); real-Postgres run of the watch suites (gfsWatch*, gfs.externalGfsRead*, entityChangeStreamRetirement, externalSessionCurrentness, routes.externalGfsRateLimitFailClosed): 27 files / 333 tests passed. db.realPostgresMigration fails 41 of 75 cases on the test host because its production access verifier shells out to psql, which is not installed there; the same 41 fail on dev. external-rest-api at this head: tsc --noEmit clean, npm test 56 files / 576 tests passed.

Risks / follow-ups

• Merge together with feat(desktop-app): refresh GFS previews and folders live over the watch stream #1503. The current desktop still calls /entity-changes/stream, which now answers 404.
• Migrations 0140 to 0145 add triggers on hot tables (team_members, users). Each one runs with a 10 s lock_timeout; the two hot ones retry a lost lock up to their declared count.
• The root-listing window has no ceiling and is not single-flight: a mass move by a legitimate user can saturate the watch pool. A failed roots query only drops that notice (the client refetches roots on every ready and on focus); the session and authorization queries that share the pool fail safe (reauthorize, reopen), so no revocation is lost. Follow-up: GFS watch: cap the root-listing window and make it single-flight #1505.
• Restoring an ancestor while a key under it is being authorized can leave that key accepted with a cut chain, and a later soft delete or move of the ancestor does not revoke it. No GFS writer restores today; this must be fixed before one is added. Follow-up: GFS watch: a restore during authorization leaves a key with a cut ancestor chain #1506.
• File budget: 45 files in 3 services (control-api, ERA, and 3 control-ui test files updated for the retirement); 25 are test files (23 suites, 2 helpers) and 6 are deletions. The retirement cannot be split from the push it relies on.

Stack

Live GFS subscriptions ship as a stack. The server half and the desktop half must reach dev together: the server PRs retire the route the current desktop uses, and the desktop PR needs the new watch route.

#	PR	Base	Scope
1	#1496	dev	gfs-controller: drive name validation, principal_denied reason
2	#1497	dev	host-context-controller: drive name validation (merge after 1)
3	#1498	dev	control-api: shared building blocks, per-resource change trigger
4	#1499	3	control-api: watch registry, listener, process runtime
5	#1500	4	control-api: GET/PUT /external/gfs/watch
6	#1501	5	external-rest-api: GET/PUT /api/v1/me/gfs/watch
7	#1502	6	control-api + ERA: authorization and session push, retire the per-user entity-change stream
8	#1503	7	desktop-app: watch client, live previews and folders

1 and 2 are independent of the chain and safe to merge on their own (1 before 2, since the controller check in 2 mirrors the one in 1).

3 to 8 are one unit and should not be deployed partially:

• 3 and 4 add groundwork; the only new runtime behavior is the gfs_resource_changed NOTIFY trigger, which nothing listens to yet.
• 5 and 6 expose the route, but until 7 lands an authorization or session change does not cut the changed events of a stream that is idle (no op in flight). Do not ship 5/6 without 7.
• 7 removes the per-user entity-change stream (ERA /api/v1/entity-changes/stream and control-api /external/entity-changes/stream), which the current desktop still uses. Do not ship 7 without 8.