Skip to content

docs(concepts): explain content addressing as free versioning#3471

Merged
jessiemongeon1 merged 4 commits into
mainfrom
bedu-603-content-addressing-versioning
Jun 17, 2026
Merged

docs(concepts): explain content addressing as free versioning#3471
jessiemongeon1 merged 4 commits into
mainfrom
bedu-603-content-addressing-versioning

Conversation

@reemsabawi-mystenlabs

Copy link
Copy Markdown
Contributor

Adds a Content addressing and versioning section to Walrus Fundamentals (docs/content/system-overview/core-concepts.mdx), explaining how a content-derived blob ID gives immutable versioning for free. Prose only, per the Sui docs style guide.

BEDU-603

What's new

  • A content-derived blob ID means every version is its own blob (nothing overwritten), lineage is an ordered list of blob IDs, identical content dedups automatically, and a blob ID is tamper-evident proof of content for provenance and reproducibility.
  • Version with a manifest blob: the pattern of keeping a small manifest blob mapping logical names to per-version blob IDs, where updating appends a new entry pointing at the new content-addressed blob.

Open questions for reviewers

  1. Scope of the property vs. Quilt: the dedup / immutable-versioning behavior holds for regular blobs and for a quilt as a whole, but not for individual items inside a quilt (their QuiltPatchId is not content-derived). This section stays at the blob level. Should I add an explicit cross-reference/caveat tying this to the Quilt page (pairs with PR 1's third question)?
  2. Section placement: added as a new top-level ## section at the end of the page. If you'd prefer it nested under an existing section or placed earlier (for example, right after the intro that introduces blob immutability), say where and I'll move it.
  3. blob ID vs BlobId: used prose "blob ID" to match this page's existing style; the Quilt/client pages use the inline-code BlobId/QuiltPatchId forms. Flagging in case you want one convention across pages.

Add a concept section to Walrus Fundamentals describing how a content-
derived blob ID yields immutable versioning for free: every version is
its own blob, lineage is an ordered list of blob IDs, identical content
dedups automatically, and a blob ID is tamper-evident proof of content
for provenance and reproducibility. Document the manifest-blob pattern
for mapping logical names to per-version blob IDs.

BEDU-603
@jessiemongeon1

Copy link
Copy Markdown
Contributor

Style Guide Audit

All 1 file(s) pass the style guide audit.

@github-actions

github-actions Bot commented Jun 17, 2026

Copy link
Copy Markdown
Contributor
PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-17 21:37 UTC

@github-actions

github-actions Bot commented Jun 17, 2026

Copy link
Copy Markdown
Contributor

📋 afdocs check results

URL: https://MystenLabs.github.io/walrus/pr-preview/pr-3471/

Running checks on mystenlabs.github.io/walrus/pr-preview/pr-3471/...

Agent-Friendly Docs Check: https://MystenLabs.github.io/walrus/pr-preview/pr-3471/
Timestamp: 6/17/2026, 9:11:45 PM

content-discoverability
  ✓ llms-txt-exists: llms.txt found at https://MystenLabs.github.io/walrus/pr-preview/pr-3471/llms.txt
  ✓ llms-txt-valid: llms.txt follows the proposed structure (H1, blockquote, heading-delimited link sections)
  ⚠ llms-txt-size: llms.txt is 54,726 characters (between 50,000 and 100,000; consider splitting)
      Learn more: https://agentdocsspec.com/spec/#llms-txt-size
  ○ llms-txt-links-resolve: llms.txt contains 160 links, but none are under /walrus/pr-preview/pr-3471
  ○ llms-txt-links-markdown: llms.txt contains 160 links, but none are under /walrus/pr-preview/pr-3471
  ✓ llms-txt-directive-html: llms.txt directive found in HTML of all 167 pages, near the top of content
  ✗ llms-txt-directive-md: Could not fetch markdown for any of 167 pages; 167 had no markdown version
      Learn more: https://agentdocsspec.com/spec/#llms-txt-directive-md

markdown-availability
  ✗ markdown-url-support: No pages support .md URLs (0/167 tested)
      Learn more: https://agentdocsspec.com/spec/#markdown-url-support
  ✗ content-negotiation: Server ignores Accept: text/markdown header (0/167 pages return markdown)
      Learn more: https://agentdocsspec.com/spec/#content-negotiation

page-size
  ✓ rendering-strategy: All 167 pages contain server-rendered content
  ○ page-size-markdown: Skipped: dependency check did not pass
  ✓ page-size-html: All 167 pages under 50K chars (median 41K HTML → 8K markdown (80% boilerplate))
  ✗ content-start-position: 24 of 167 pages have content starting past 50% (worst 71%)
      Learn more: https://agentdocsspec.com/spec/#content-start-position

content-structure
  ✓ tabbed-content-serialization: 53 tab group(s) across 30 of 167 pages; all serialize under 50K chars
  ✓ section-header-quality: 2 page(s) with tab headers checked; headers include variant context
  ✓ markdown-code-fence-validity: All 0 code fences properly closed across 1 pages

url-stability
  ✓ http-status-codes: All 167 pages return proper error codes for bad URLs
  ✓ redirect-behavior: No redirects detected across 167 pages

observability
  ✗ llms-txt-coverage: llms.txt covers 0/159 sitemap doc pages (0%); 159 missing
      Learn more: https://agentdocsspec.com/spec/#llms-txt-coverage
  ○ markdown-content-parity: Skipped: dependency check did not pass
  ✓ cache-header-hygiene: All 168 endpoints have appropriate cache headers

authentication
  ✓ auth-gate-detection: All 167 pages are publicly accessible
  ○ auth-alternative-access: All docs pages are publicly accessible; no alternative access paths needed

Summary
  12 passed, 1 warnings, 5 failed, 5 skipped (23 total)

Full spec: https://agentdocsspec.com/spec/

Comment thread docs/content/system-overview/core-concepts.mdx Outdated
Comment thread docs/content/system-overview/core-concepts.mdx Outdated
reemsabawi-mystenlabs and others added 2 commits June 17, 2026 16:56
Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com>
@jessiemongeon1 jessiemongeon1 merged commit 63549ee into main Jun 17, 2026
31 checks passed
@jessiemongeon1 jessiemongeon1 deleted the bedu-603-content-addressing-versioning branch June 17, 2026 21:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants