Document Table.oldestRetainedAuditTime() and the subscription catch-up horizon - #660
Conversation
…n catch-up horizon `subscribe`'s `startTime` catch-up reads the audit log, so a consumer resuming past `logging.auditRetention` gets a replay that begins after the messages it missed. Nothing in the reference said so, because until now there was no supported way to detect it. Documents `Table.oldestRetainedAuditTime()` (HarperFast/harper#2447) with the resume pattern, and notes the horizon on the `startTime` row so a reader meets the caveat where they meet the option. Covers the parts a consumer can get wrong: the shared time domain, the database-scoped floor, `Infinity` as the fail-closed unknown, the one-way error direction, and that the reading is not a lock. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the API documentation in reference/resources/resource-api.md to introduce the new oldestRetainedAuditTime() method, which helps consumers detect if subscription catch-up history has been pruned. It also links to this method from the startTime property description. The review feedback focuses on improving the readability of critical safety warnings and fallback behaviors by splitting combined concepts and semicolon-separated clauses into distinct, separate sentences.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-660 This preview will update automatically when you push new commits. |
|
Core PR: HarperFast/harper#2458 (issue HarperFast/harper#2447). |
…tences Per review on #660, and the repo guidance it cites: a warning a reader needs to find while scanning should not be joined to a definition by "and" or hidden behind a semicolon. "Treat no cursor as safe" now stands on its own rather than trailing the definition of `Infinity`, and the one-direction guarantee is two sentences instead of a semicolon. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-660 This preview will update automatically when you push new commits. |
…r cursor Chris caught a real gap on #660. The `getHistory` caveat was in auditStore.ts's JSDoc, Table.ts's JSDoc and resources/DESIGN.md, but not on the reference page — which is the one place a consumer building this check would actually look. The #660 description claimed it was covered; it was not. It matters because the two values share a name and differ only under backdated or replicated writes: a consumer that persists `getHistory().localTime` can pass `cursor >= floor` while the messages between them are already pruned, which is exactly the silent gap the accessor exists to expose. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-660 This preview will update automatically when you push new commits. |
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
"It does not report a cursor as safe when a prune removed history that cursor needed" was stated absolutely, and the validity bullet four lines above documents a counterexample inside its own scope: a persisted `getHistory().localTime` is an origin version, so a record written with origin 900 can sit at audit key 400. Persist 900 against a floor of 500 and the check passes while the consumer's real position (400) is below the floor. No restore involved — this is pruning, which is exactly what the "Across retention pruning" qualifier admits. Conditions the claim on cursor validity and names the excluded case in the load-bearing sentence itself, so a reader lifting that sentence to restate the contract carries the condition with it. That is how the two previous overclaims travelled. Predates this branch (#660), so the fix is a correction rather than a regression, but the failure shape is the same.
3 participants
Documents
Table.oldestRetainedAuditTime()(HarperFast/harper#2447, HarperFast/harper#2458) and the subscription catch-up horizon it exists to make detectable.subscribe'sstartTimecatch-up reads the audit log, so a consumer resuming pastlogging.auditRetentiongets a replay that begins after the messages it missed. The reference said nothing about it, because until now there was no supported way to detect it.Adds a section after
subscribewith the resume pattern, and notes the horizon on thestartTimerow so a reader meets the caveat where they meet the option. Covers the parts a consumer can get wrong: the shared time domain (and thatgetHistory'slocalTimeis not in it — it reports the origin version under that name), the database-scoped floor,Infinityas the fail-closed unknown, the one-way error direction, and that the reading is a moment in time rather than a lock.Verification
npm run format:check— clean.npm run build— clean, no broken links (the in-page anchor to the new section resolves).v5.3.0: newest core tag isv5.2.7and the core PR is milestoned v5.3, so this ships in the next minor.