reeflog-client 0.7.21 → 0.7.23

package/README.md

@@ -5,7 +5,7 @@ they did to account balances for selected programs into a cursor-addressed
 append-only log, so a consumer resumes without gaps after a crash,
 disconnect, or reorg.
 
-**Status: v0.7.21 shipped (2026-11-13), v0 working.** Live against mainnet-beta: see *Measured results* below. Install the binary without a Rust toolchain: `npm install reeflog-client` then `import { bootstrap } from 'reeflog-client'; await bootstrap()` (downloads the prebuilt release archive and verifies its sha256; the archive digests are `6bfec083…` linux / `303d0836…` macos, both equal what the release API publishes). The same install from the tagged release: `npm install github:auroraxo/reeflog#v0.7.21`. Or from source: `cargo install --git https://github.com/auroraxo/reeflog --tag v0.7.21`. The full event envelope (logs, balances, instructions, account list with owners, the bytes each account held, and the authority each token account had at the moment of the event), the Node client (see *The Node client*), webhook fan-out, a dead-letter queue, and archive backfill ship in this tree; Yellowstone as a second transport does not.
+**Status: v0.7.23 shipped (2026-11-13), v0 working.** Live against mainnet-beta: see *Measured results* below. Install the binary without a Rust toolchain: `npm install reeflog-client` then `import { bootstrap } from 'reeflog-client'; await bootstrap()` (downloads the prebuilt release archive and verifies its sha256; the archive digests are `747e2db8…` linux / `fc2bcecc…` macos, both equal what the release API publishes). The same install from the tagged release: `npm install github:auroraxo/reeflog#v0.7.23`. Or from source: `cargo install --git https://github.com/auroraxo/reeflog --tag v0.7.23`. The full event envelope (logs, balances, instructions, account list with owners, the bytes each account held, and the authority each token account had at the moment of the event), the Node client (see *The Node client*), webhook fan-out, a dead-letter queue, and archive backfill ship in this tree; Yellowstone as a second transport does not.
 
 ## The idea
 
@@ -271,13 +271,24 @@ distinguishes four states:
   incomplete passes exit 3 (same honesty rule as `verify` and `repair`).
 
 `reeflog tail` delivers the log array by default; `--no-logs` keeps the
-compact identity-only shape. A background worker hydrates recovered rows
-continuously, beside the ingest loop — not once at startup, because the
-periodic repair pass keeps recovering rows while the daemon runs, and a
-killed run never reaches a shutdown pass. A final pass runs at shutdown.
-Verified live: `tools/e2e-payload.mjs` checks all 13 conditions against
-mainnet, including independent byte-for-byte comparison of stored payloads
-against freshly fetched transactions.
+compact identity-only shape. Since v0.7.22 the default (payload-bearing)
+tail shares the delivery rule the accounts filter already had: a row the
+payload queue still owes (`logs IS NULL AND payload_state IS NULL`) HOLDS
+the delivery — rows before it are handed over, the cursor stays behind the
+owed row, tail exits 3 naming `hydrate`, and the same cursor reads the row
+complete once the debt is paid. Measured on the pre-fix tree (v0.7.21):
+tail consumed a pending row, hydrate filled it, and the next pass reported
+`0 events after cursor 2` — the payload existed in the journal and never
+reached the consumer that had already been walked past it. Recorded
+outcomes (`unavailable` / `invalid`) are still delivered in-line with their
+marker — they are answers, not debts — and `--no-logs` callers are never
+held (they asked for identities only). A background worker hydrates
+recovered rows continuously, beside the ingest loop — not once at startup,
+because the periodic repair pass keeps recovering rows while the daemon
+runs, and a killed run never reaches a shutdown pass. A final pass runs at
+shutdown. Verified live: `tools/e2e-payload.mjs` checks all 13 conditions
+against mainnet, including independent byte-for-byte comparison of stored
+payloads against freshly fetched transactions.
 
 ## What the event did to accounts
 
@@ -872,7 +883,24 @@ reeflog start --db reeflog.db --webhook-config webhooks.json --webhook-every 5
    in chain order and never with a hole in front of it. It may see one
    twice; the stable id (`X-Reeflog-Event-Id: <target>:<kind>:<seq>`) is
    what a consumer dedups on for exactly-once.
-3. **The payload is authenticated.** Every request carries
+3. **A payload the journal still owes is not delivered.** A row whose
+   content the journal owes (`logs IS NULL AND payload_state IS NULL`) is a
+   signature, not an event — since v0.7.23 the event queue HOLDS at it:
+   rows before it are delivered, the target's cursor stays behind the owed
+   row, no receipt is written, `push` exits 3 naming `hydrate`, and once the
+   debt is paid the SAME target receives the row complete. Measured on the
+   published v0.7.22 asset (`research/webhook-payload-hold-baseline-v0722-
+   2026-11-13.json`, verdict `webhook-payload-hold-defect-present`): the
+   receiver got the owed row as a signed body with `logs: null`, `next_seq`
+   moved 0 → 1, a receipt was written, and the second pass after `hydrate`
+   delivered nothing — the finished event was permanently unreachable for
+   that consumer while a fresh target read it. This is the same rule
+   `tail` holds since v0.7.22, one channel over: the webhook body is
+   SIGNED, so a receiver cannot tell a signature without content from a
+   real event. A recorded outcome (`unavailable` / `invalid` / `no_metadata`)
+   is never held — it is an answer, not a debt — and retractions are never
+   held by this rule either.
+4. **The payload is authenticated.** Every request carries
    `X-Reeflog-Signature: sha256=<hex>` = HMAC-SHA256(secret, body) over the
    exact bytes sent (canonical JSON — `serde_json`'s sorted keys, so the same
    event always produces the same signature). The receiver checks it with
@@ -882,14 +910,14 @@ reeflog start --db reeflog.db --webhook-config webhooks.json --webhook-every 5
    import hmac, hashlib
    want = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    ```
-4. **A retraction is delivered too**, on its own cursor, and it is delivered
+5. **A retraction is delivered too**, on its own cursor, and it is delivered
    *even when the event queue is blocked behind a refusal* — a retraction is
    the one message whose lateness costs money.
-5. **Receipts make the crash window safe.** The state (per-target cursor)
+6. **Receipts make the crash window safe.** The state (per-target cursor)
    and the receipts (which exact body was accepted, by sha256) live in the
    journal. A daemon that dies between "POST succeeded" and "cursor advanced"
    does not deliver the event twice on the next pass.
-6. **A refusal stops being a verdict only when it stops repeating.** One
+7. **A refusal stops being a verdict only when it stops repeating.** One
    4xx can be an accident (mid-deploy, a config reload), so the refusal is
    counted. After `dead_letter_after` refused attempts on the same event
    (default 5, `0` disables it) the event moves to the **dead-letter queue**:
@@ -1647,11 +1675,11 @@ is the harness's own).
 
 The CLI is a contract before it is a convenience: exit 0 delivers and
 advances the cursor, exit 3 (on `tail`) means the delivery **held** at a row
-whose account envelope is still owed — rows before it are delivered, nothing
-at or after it is consumed — and exit 1 is a refusal. A consumer that maps
-those three outcomes wrongly either replays rows forever or drops the owed
-row without ever seeing it. Until now every Node consumer had to derive that
-by hand.
+whose payload or account envelope is still owed — rows before it are
+delivered, nothing at or after it is consumed — and exit 1 is a refusal. A
+consumer that maps those three outcomes wrongly either replays rows forever
+or drops the owed row without ever seeing it. Until now every Node consumer
+had to derive that by hand.
 
 `index.js` (npm package `reeflog-client`, MIT, zero dependencies, Node ≥ 18)
 ships that mapping as one file. It never opens the journal — every call runs
@@ -1660,7 +1688,7 @@ contract, and a library's idea of the schema cannot drift from the daemon's.
 
 ```bash
 npm install reeflog-client                     # the registry; this version, no Rust toolchain
-npm install github:auroraxo/reeflog#v0.7.21   # the same client from the tagged release
+npm install github:auroraxo/reeflog#v0.7.23   # the same client from the tagged release
 ```
 
 The client needs the `reeflog` binary. `bootstrap()` gets it **without a
@@ -1809,10 +1837,11 @@ Checked on 2026-10-23: Solana client errors already name the failure modes, incl
 reeflog does not recover account bytes from before an event, and the account
 envelope is balance MOVEMENTS an event caused — not the state of the accounts
 involved. `tail --with-accounts` does not skip past a row whose envelope has
-not been fetched yet: it holds the cursor there and exits 3 until
-`hydrate --accounts` pays the debt, so an owed row can never be lost to the
-consumer. Rows the chain itself made unfillable are the only ones skipped,
-and each skip is reported. That is a different problem.
+not been fetched yet, and since v0.7.22 the default tail holds the same way
+for a row whose payload is still owed: the cursor stays, tail exits 3 until
+`hydrate` (or `hydrate --accounts`) pays the debt, so an owed row can never
+be lost to the consumer. Rows the chain itself made unfillable are the only
+ones skipped, and each skip is reported. That is a different problem.
 Public WebSocket endpoints are also rate-limited, so provider independence
 has to be real rather than assumed.
 

package/index.js

@@ -8,8 +8,9 @@
 // product:
 //
 //   exit 0 — the batch is fully delivered, the cursor advanced;
-//   exit 3 — the delivery HELD at a row whose account envelope is still owed
-//            (tail), or the scan proves nothing (verify/repair/hydrate).
+//   exit 3 — the delivery HELD at a row whose payload or account envelope is
+//            still owed (tail), or the scan proves nothing (verify/repair/
+//            hydrate).
 //            Rows before the hold WERE delivered; nothing at or after it was
 //            consumed. Treating exit 3 as "failure, retry the batch" replays
 //            rows; treating it as success silently drops the owed row;
@@ -199,8 +200,9 @@ export class Reeflog {
    * CONSUMED (delivered, or skipped because a recorded outcome made it
    * permanently undeliverable). On exit 3 the hold row and everything after
    * it are NOT consumed — the next call returns them once the debt is paid
-   * (`reeflog hydrate --accounts`), so nothing is ever lost to a consumer
-   * that acted on a partial batch.
+   * (`reeflog hydrate`, or `reeflog hydrate --accounts` for the account
+   * envelope), so nothing is ever lost to a consumer that acted on a partial
+   * batch.
    *
    * @param {object} [opts]
    * @param {number} [opts.limit=1000]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reeflog-client",
-  "version": "0.7.21",
+  "version": "0.7.23",
   "description": "Node client for reeflog, the durable local mailbox for Solana events: cursor-based event delivery, retractions, health and repair.",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "node --test"
   },
   "dependencies": {
-    "reeflog-client": "github:auroraxo/reeflog#v0.7.20"
+    "reeflog-client": "github:auroraxo/reeflog#v0.7.22"
   }
 }