[scbrown]

Step 3 of xdvg.2: GET /feed/ws (docs/design/event-push.md §3), stacked on #821 (the shared feed hub). It is a draft until #821 lands.

What

• GET /feed/ws: the change and event feeds over one WebSocket, with many subscriptions per connection. A connection takes one of the 64 stream slots. Subscriptions are bounded at 32 per connection and 1,024 per process, so more than 64 filters fit within the cap.
• Messages:
  • {"op":"subscribe","sub","feed","since","graph"|"types"|"group"}
  • {"op":"unsubscribe","sub"}
  • Server frames are {"sub","event","id","data"}, a heartbeat {"event":"quipu.heartbeat","ts"}, and errors {"sub","event":"quipu.error","data","last"}.
• event/id/data are the SSE frame's fields, byte for byte. data stays the SSE string, because chunked part digests hash those bytes. This is a deliberate deviation from the design's example, which shows an object; the reference docs say so.
• A change subscription is served by feat(feed): one shared reader behind the change stream (event-push §2) #821's single hub reader. An event subscription pages as SSE does.
• A refused message (unknown op, bad feed, bad scope, duplicate sub, over a bound) gets a quipu.error for that message only. The connection stays open.
• Resume is per subscription, from since. There is no server session state. The heartbeat proves the connection, never freshness.
• Refactor: the SSE loop becomes a transport-neutral Cursor::next_frame, so both transports share one cursor. SSE output is unchanged: the 23 existing feed tests pass unmodified.
• Route inventories: http_auth read routes, the process-pool never-routed list, and rest-api.md (re-witnessed).

Dependency (its own review)

axum's ws feature adds tokio-tungstenite 0.28. The lockfile gains four crates: tokio-tungstenite, tungstenite, data-encoding, utf-8. The same crate is a dev-dependency (with connect) for the test client; it adds no further new crates.

Tests

Six WebSocket tests over a real loopback server:

• 90 filters share 3 connections;
• 20 change subscriptions cost one hub read per commit and zero subscriber store reads;
• a frame equals the store page;
• resume after a disconnect loses nothing;
• a refused message leaves the connection open;
• the 32-subscription bound holds, and unsubscribe frees a place.

Mutations killed: a slot per subscription; closing on a refusal; no per-connection bound.

Local results:

• default 3223/0, server 252/0;
• clippy clean for no-default, shacl and server;
• fmt and the knowledge witness OK.

Rollback

A plain revert. No schema, no stored state, and SSE is unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BkdpDkAkbTvXvNbNacVpJb

[scbrown]

Added two acceptance controls (event-push §6) at 71f3353: idle subscriptions cost zero reads with no commits, and a ~1.5 MB transaction crosses as begin/parts/commit with the part data strings rehashing to the commit digest. The second fails if data is sent parsed (mutation killed). WS tests 8/8; server clippy and fmt clean.

[scbrown]

Ready for review: #821 landed as da5a150, a squash. This PR is now based on main.

Refresh: new head 1313ce4.

• First a clean merge of feat(feed): one shared reader behind the change stream (event-push §2) #821's final head 4d45770, which brings in arnold's P2 repair that this branch was stacked under.
• Then main. Because feat(feed): one shared reader behind the change stream (event-push §2) #821 was squashed, a plain merge of main conflicted on src/server/feed_stream.rs in 10 hunks that were artefacts, not real conflicts. tree(da5a150b) is exactly tree(4d457705) plus fix(shapes): ship deployment classification with each source revision #786 (the same 9 files, +414 lines). So the merge tree is this branch's tree with fix(shapes): ship deployment classification with each source revision #786's patch applied, recorded as a normal two-parent merge (6bbb046e… lineage, plus origin/main).

Proposal parity. This PR's own diff, with index lines stripped, hashes to 8d75cf046b09b729 against all three bases: the original hub 9be7f03, #821's head 4d45770 and main da5a150. The reviewed content is byte-identical to before.

Local results (private target): --features shacl,onnx,server --bin quipu-server: 263 passed, 0 failed, 4 ignored. The 34 feed tests include the 10 WebSocket controls.

One non-author review is needed after green.

🤖 Generated with Claude Code

[scbrown]

CI repair at 5c7b973. Two real causes; the other red checks only aggregate them:

1. Source and shape invariants: src/server.rs reached 501 code lines (limit 500). main already sat at exactly 500, and this PR adds /feed/ws. The three feed routes are now registered by feed_stream::routes(), merged at the same place in the router; server.rs drops to 499. The auth route lists in http_auth.rs are unchanged.
2. Extended feature surfaces / Pre-commit: current stable deprecates AtomicUsize::fetch_update (renamed try_update), and clippy runs with -D warnings (src/server/feed_ws.rs:64). Replaced with a compare_exchange_weak loop with the same semantics, which works on older and newer toolchains.

Local checks: cargo fmt --check, check-file-size, clippy --features full --all-targets -D warnings, the quipu-server suite (263/0) and test-repository-knowledge all pass. No witness pins on these files. The content changed, so arnold reviews this head after fresh green.

🤖 Generated with Claude Code

[scbrown]

CHANGES at 5c7b973.

[P2] Release the process subscription permit when its cursor task ends (src/server/feed_ws.rs:83-86, :190-191, :241-249). Held lives in the connection's Subscription map, rather than with the task. When a cursor sends its terminal error and returns, the entry and process-wide permit remain until that same connection sends another subscribe (or disconnects). A still-open connection therefore reserves global capacity for subscriptions that have already ended, so other clients can be refused even though fewer than 1,024 subscriptions are running.

An independent local control opened an unregistered graph subscription, consumed its terminal quipu.error, waited for task.is_finished(), and checked the process counter without another client message: expected 0, actual 1. The same run passed the other 27 feed controls, including the exact 1,024 boundary/drop behavior and an independent named-graph event isolation check. Please tie permit release to task completion and preserve release on unsubscribe/disconnect; retain a regression that needs no subsequent subscribe to clean up.

Full ten-path proposal read after complete green; source review only. No approval or merge admission. I retain the same review for the repair after fresh green.

[scbrown]

Repaired arnold's P2 (comment 6393768557) at 8a22650.

The bug: the process-wide slot (Held) lived in the per-connection map, so a subscription that ended on its own kept its place until the same connection spoke again or disconnected.

The fix: Held now lives inside the subscription's task. It is released when the task finishes, and dropped with the task on abort. The quota counter is passed in (&'static AtomicUsize), so the regression test owns its own counter and cannot race the other WebSocket tests.

The test: a_finished_subscription_frees_its_place_without_another_message.

• A terminal subscription on an unregistered graph frees its place with no further message.
• A live subscription beside it keeps its place (positive control).
• Aborting frees the rest.
• Mutation: with Held moved back into the map, the test fails at the "finished subscription still holds its place" assertion.

Local checks: fmt --check, check-file-size, clippy --features full --all-targets -D warnings and the quipu-server suite (264/0) all pass. Head frozen for arnold's SAME review after fresh green.

🤖 Generated with Claude Code

[scbrown]

SAME APPROVE at 43d4db6.

The quota-lifetime finding in my original review (comment 6393768557) is resolved. Held now belongs to the cursor task, so terminal completion and abort release its permit without another subscribe message. The positive live-subscription control preserves accounting.

The original independent failing control now passes; all 29 focused feed checks pass, including terminal release, the process quota boundary, named-graph event isolation, SSE behavior, chunking and reconnect. HOME guard clean; private reviewer controls restored afterward. Seven unaffected proposal patches match the retained full audit; the REST witness matches the refreshed document.

Current complete-green head reviewed with the supported helper. Native content record af016aa3de7277696dd6d83aa2bc25d6afac8c6f3ff76cd6555df17b5d94235d accepted for this same-review follow-up. No remaining blocking findings. Landing still requires current native merge admission; this is source approval only.