HarperFast / HarperFast/harper

Subscription surfaces document no delivery guarantee, and the rawEvents bypass is unreachable from any shipped handler

Open
#2,483 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.