Repository navigation
feat: support readable snapshots and independent Reader navigation - #142
Merged
Merged
Conversation
suguanYang
marked this pull request as ready for review
October 30, 2026 05:09
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Progressive consumers can prepare an immutable readable snapshot before image replication finishes, authorize selected image URLs in one batch, and fetch the initial coarse directory independently. Full-copy commits, cancellation ownership, and snapshot integrity remain separate from readability.
Stored snapshot reads select a requested physical page before normalizing bodies and resolving asset URLs.
knowledge.getDocumentSummary(reference)independently returns the complete verified metadata index, including physical pages, chapter paths and embedded-asset ownership, without constructing rich bodies, reading table/image files or generating asset URLs. A slow body read can therefore no longer block a complete Tree. The full stored JSON is still read and scanned. Remote-only references require a prepared or synchronized snapshot; unversioned local results cannot claim a requested snapshot identity. Existing full-copy readers retain their previous acceptance behavior.The exported SDK version follows the package manifest and beta snapshot publishing rebuilds runtime metadata after versioning. Minor changesets prepare the release.
Validation on the current head: 576 SDK unit tests, typecheck, lint, and CJS/ESM/declaration builds pass. The actual packed candidate passes Hipo typechecking, 2,615 unit tests and 52 selected Chromium tests. Coverage includes independent Tree/page loading and retries, snapshot replacement, explicit trace provenance, stalled first-page navigation to pages 150 and 151, and existing full-copy table compatibility. Current-head Node 20/22 CI, including package installation, passes.
A current production-build acceptance on the same existing 188-page snapshot held the first-page request for 30 seconds. The complete Tree appeared in 1.959 seconds with all 144 chapter sections and 188 unique page references. Its metadata RPC returned 41,795 bytes without body entities or access URLs. Distant page 150 and Next to 151 retained the same snapshot and original image keys while page 1 remained held. No complete read, Fine, ingestion, Ask or export was triggered. This is one correctness sample; image decoding still took 16.398 and 6.758 seconds over the unchanged media transport.
A prior production-build comparison of the same 188-page snapshot reduced the Reader response from 944,521 to 42,846 bytes and the observed RPC median from 12.014 to 2.324 seconds across three representative reads per version. The unchanged first-page image is approximately 3.16 MB; variable image transfer prevents a stable end-to-end latency claim. That comparison predates the new independent summary API. Earlier packed candidates separately passed the complete 188-page upload, export and Ask/citation flow.
Hipo must pin and validate the actual published registry version before deployment. Packed-candidate validation does not satisfy registry-backed frozen installation or hosted release acceptance. Worker, API and transfer concurrency are unchanged.