HarperFast / HarperFast/harper
Subscription surfaces document no delivery guarantee, and the rawEvents bypass is unreachable from any shipped handler
- Dominant language
- JavaScript
- Stars
- 89
- Forks
- 10
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 200
Description
## Summary
No Harper subscription surface documents what it guarantees about **delivery of intermediate transitions**, and the one internal bypass that would provide full-stream delivery is not reachable from any shipped protocol handler.
This is a documentation and API-surface gap, **not** a data-loss bug. The behaviour itself is correct as a *cache* semantic and is already pinned as expected behaviour by an integration test on `main` (`integrationTests/resources/subscription-delivery-completeness.test.ts`, landed in PR #2070): under burst writes the terminal value is always correct across in-process `subscribe()`, SSE and MQTT. What is missing is (a) saying so anywhere a user would look, and (b) any way for a consumer who needs every transition to opt into one.
## The measurement
Under burst writes at `threads: 4`, up to **88.5%** of transitions are coalesced away — silently, with no error and no gap marker — across all three surfaces. A cache or last-value-wins consumer is unaffected. A CDC, audit, or event-sourcing consumer loses most of the stream and has no way to detect that it did.
## The unreachable bypass
`resources/Table.ts` gates the full-audit-value path behind `request.rawEvents`. A grep of `server/` on `origin/main` returns **zero** hits for `rawEvents` — no shipped protocol handler sets it, and `resources/ResourceInterface.ts` does not expose it. So the capability exists in the resource layer and is unreachable from outside.
## What this issue asks for
1. Document the delivery semantic each subscription surface actually provides (coalescing under load, terminal value correct, no gap marker).
2. Decide whether the `rawEvents` bypass should be exposed on any surface, or removed as dead. Leaving an unreachable branch in a hot path is the worst of the three options.
Cite the already-landed test as the behavioural baseline; there is no need to re-measure.
## Dup check
Six searches across harper and harper-pro ("subscription coalesce", "rawEvents", "full-stream delivery", "latest-value-wins", "expose rawEvents", each in both repos): nothing tracks the delivery-guarantee doc gap or the unreachable bypass. The nearest hit, #2444 (catch-up-replay value loss), is a different mechanism — the replay path, not live coalescing.
*Found by exploratory QA (finding F-276); triaged 2026-09-02.*
Contributor guide
Research direction
Start with resources/Table.ts and resources/ResourceInterface.ts, then inspect the shipped handlers under server/ for the subscription surfaces. Use integrationTests/resources/subscription-delivery-completeness.test.ts as the behavioral baseline. Done means documenting coalescing, terminal-value correctness, and absent gap markers, while deciding whether rawEvents is exposed or removed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, nodejs
- Domain
- api, backend-api-design, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100