[zach88]

What

The per-process GFS watch registry in control-api, plus the process-level pieces it runs on. Not mounted on any route yet (#1500 does that).

• runtime.ts: a single cancel() form for timers (callers clear the handle when a timer fires); guarded / guardedTick / bestEffort covering both sync throws and async rejections; total(), raceAbort, and an injectable monotonic clock.
• readSlots.ts: process-wide FIFO semaphore of 64 concurrent gfs-controller reads, with a demand counter and response-rate buckets feeding a backlogMs() estimate used to pace retries.
• watchPool.ts: a dedicated pg pool for the watch, with client-side query timeouts, keepalive and a permanent error listener.
• listener.ts: a dedicated LISTEN client for the resource, ping and command channels. Liveness is checked by the echo of its own ping; on loss it tears down its own state first, then reconnects with capped backoff. Dispatch is total per channel, and an unreadable payload on a revocation channel fails closed through onExpansionFailed.
• recentDirty.ts: ring buffer of recent ancestry changes, used to flag an authorization decision that may have raced a move.
• registry.ts:
  • Connections with a single socket writer gated by phase, backpressure (64 KiB or 5 s pending, then slow_consumer), heartbeat, max lifetime and token expiry.
  • closeConn never throws: registry memory is released first, side effects run best-effort, and the client's retry delay is spread.
  • The authorization op: ancestry CTE, a read token per drive minted per op, bounded gfs-controller reads, a gate after every await, auth and server deadlines, suspicion on concurrent ancestry changes, and deferred keys on transient failures.
  • A mutable subscription set through the gfs_watch_cmd channel: binding check (userId, authGeneration), a seq window and a single queued command.
  • gfs_resource_changed delivery with a 250 ms fixed window that only emits accepted keys outside the op in flight.
  • open() as the API for the GET handler, with key and drive ceilings enforced before admission.
• readGfsc caps the gfs-controller response body at 64 KiB and replaces a non-uuid request id, which gfs-controller rejects.
• Metrics gfs_watch_*, including gfs_watch_cmd_dropped_total{reason}.

The authorization and session push hooks (resetWindows, onExpansionFailed) are required dependencies of the listener and are no-ops here. #1502 fills them in.

Why

A watch stream has to keep three things true while requests, NOTIFYs, timers and socket events interleave across awaits: a client only ever receives events for keys it was authorized for, a change is not lost while a subscription is being re-authorized, and a stuck client or a burst of changes cannot exhaust the process. The registry is written as an explicit state machine so each of those can be checked at rest.

How

• One writer per socket, gated by the connection's phase, so a late op result or a timer from a previous phase cannot write to a stream that has already moved on.
• Every await in an op is followed by a gate that drops the result if the connection closed or a newer op replaced it.
• Holds (connections whose user is being re-authorized) live in a structure of their own and are released by iterating that structure, never the per-user index.
• Subscription changes cross replicas through gfs_watch_cmd, so a PUT can land on a replica that does not hold the stream.

Testing

• Model-based: gfsWatch.registry.property.realPostgres drives the real registry with fast-check commands and fc.scheduler() for promise ordering, against real Postgres, the real trigger and real session/mint, with a fake gfs-controller built from its own envelope helpers. Invariants are checked at rest against a reference model.
• Scenarios: gfsWatch.registry.realPostgres (45 cases) asserts the frames the client observes.
• Unit and real-Postgres suites for runtime, readSlots, recentDirty, watchPool and listener (including listener loss through a controllable TCP proxy).
• At this head: tsc --noEmit clean; npm test 634 files / 8951 tests passed (real-Postgres suites skip in this lane); real-Postgres run of the watch suites (gfsWatch*, gfs.externalGfsRead*): 15 files / 206 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.

Risks / follow-ups

• Until feat(control-api): push authorization and session changes over the GFS watch and retire the per-user entity-change stream #1502 lands, an authorization or session change does not cut changed events on a stream that has no op in flight. This PR and the HTTP route are not meant to be deployed without feat(control-api): push authorization and session changes over the GFS watch and retire the per-user entity-change stream #1502.
• The read ceiling (64 per replica) still needs a load measurement against gfs-controller before merging the stack.

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.