docs: fused bundle-uri implementation plan#130
Open
0lut wants to merge 1 commit into
Open
Conversation
Captures what to actually do about clean-slate item (c), fusing the design intent, PR #76's implementation experience, and this session's operational findings. - Records why #76 can't be merged as-is: it advertised the pre-#79 generation-bundle chain (`bundle_key`), which #79 deleted in favor of content-addressed packs; and bundle-uri serves bundle-framed files, not raw packs, so a base bundle artifact must be published. - Phases the work: (1) salvage #76's protocol-v2 half (textual conflicts only, independently useful, prerequisite); (2) publish a content-addressed base bundle as a byproduct of generation publish/compaction; (3) advertise bundle-uri from the snapshot layout, off by default. - Calls out the cross-cutting gates that determine real value: freshness coupling (async materialize + scheduled warm so the base isn't stale), private-repo URL safety (signed/public-only), shallow/blobless scoping (full clones only), old-client fallback, and the node git-version gate. - Acceptance criteria + a dev/origin validation method. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
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
1 participant
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.
Summary
A single, pick-up-ready plan for clean-slate item (c) bundle-uri, fusing: the design-doc intent, PR #76's implementation experience, and this session's operational findings. Docs-only (
docs/bundle-uri-plan.md). No behavior change.Why this doc
We established that #76 (the bundle-uri attempt) can't be merged as-is: it advertised the pre-#79 generation-bundle chain (
bundle_key), and #79 deleted that layer for content-addressed packs — so #76 isCONFLICTINGand semantically dead. bundle-uri also serves bundle-framed files, not raw packs, so a base-bundle artifact must be published. This plan says what to do instead.The plan (phased)
bundles/bundle-{sha256}.bundle, referenced from the snapshot manifest — done off the client path.bundle_uri_enabled,bundle_uri_base_url); bytes served by S3/CloudFront/the existing Cloudflare front door, node serves only the small top-up.Why it matters (measured)
Offloads the cold-clone base bytes to S3/CDN → attacks the linux ~233s read-through, the Cloudflare ~100s origin cap (node response becomes a small top-up), and the no-bitmap
pack-objects+ mutation-lock contention.Cross-cutting gates (the fusion)
/v1/materializetimes out at Cloudflare and never publishes).Includes acceptance criteria and a dev/origin validation method.
🤖 Generated with Claude Code