Transclusion Architecture

How content reuse works in Xudanu — what we built, what we're building, and how it connects to the Xanadu lineage

How It Works Today

Current Implementation

Structural Transclusion (FR-37)

The largest architectural change since this document was first written: transclusions now live inside the document model itself, as an inline RangeElement::Transclusion element in the O-tree — one source of truth, where the earlier design kept a separate compound side-table (which could drift from the text).

• Single source of truth — the transclusion IS an element; editing, persistence, and replication all operate on the same structure
• Placement at any position — transclusions can be placed wherever the cursor is, not just appended; the placement UI supports pinned quotations
• Generation-stamped caches — resolved content is cached and invalidated by generation checks, so readers never see stale transclusions (re-resolved on read)
• Span migration through deltas — edits inside materialized transcluded regions split like ordinary text, and dependent caches re-check on source change
• Trails as derived works — a trail's pinned spans materialize into a real derived edition, generation-checked against its sources

Content-Addressed Transclusion (FR-26)

Since v1.1, every new transclusion stores a BLAKE3 content hash alongside the range reference. This means:

• Tamper detection — if the source passage is edited after transclusion, the hash mismatch is logged
• Version awareness — the source revision is recorded, so "what was this when I transcluded it?" is answerable
• Immutability — Phase 3 snapshots content to the blob store, so transclusions survive even if the source is deleted

Recursive Resolution

Transclusions can chain: Document A transcludes from B, which transcludes from C. Xudanu resolves these chains recursively up to 32 levels deep, with automatic cycle detection.

Span Migration

When a source document is edited, the character positions of transclusions referencing it need to update. Xudanu uses delta-based span migration: the text delta (insert/delete operations) is used to compute new positions for all affected transclusion ranges.

What We Don't Have (Yet)

Spanfilade

Gold's spanfilade is a fundamentally different model. Instead of referencing character positions, it inserts content at the I-stream level — a layer below character offsets. This means:

• Transclusions survive arbitrary restructuring of the source (not just inserts/deletes)
• Transcluded content can be from a specific version that's been superseded
• The enfilade tree preserves all versions simultaneously — no separate revision history needed

Cross-Server Transclusion

Cross-server transclusion works today (FR-6): a transclusion references a tumbler "server.domain".work_id.revision.start-end, and the content is fetched from the remote server with BLAKE3 hash verification and Ed25519 trust-on-first-use server identity (pinned on first contact, change-detected thereafter). A transclusion from another server renders exactly like a local one, and its provenance chain reaches across the network. See the network guide for the trust model and the adversarial resilience notes for how peer-supplied content is validated at the boundary.

The Xanadu Connection

The key architectural choices:

Visual Walkthrough

Real screenshots of transclusion in action. These are not mockups.

1. Start with a source document

The source document contains the original text. Any passage can be transcluded into other documents.

This is the document we'll pull a passage from. The text lives here and maintains its provenance.

2. Select a passage to transclude

Select text in the source document and click the Transclude button. The passage is held in memory.

The selected passage will maintain a live link back to this source document.

3. Place the transclusion

Navigate to the destination document and click to place the transclusion. The excerpt text appears inline.

The placed content is a live reference, not a copy. If the source is edited, the transclusion updates.

4. Transcluded content with provenance

The placed transclusion shows its source origin. The derivation chain traces the content back to its original author.

Each transclusion carries the original author's attribution through the chain — this is the Xanadu principle in action.

5. Transclusion visible in Connections

The Connections panel shows all transclusions in the current document — source title, excerpt, and character range.

Click an entry to highlight the transclusion in the document. A ⚠ changed badge appears if the source was edited after transclusion.

Try It Yourself

# Clone and build
git clone https://github.com/jonesd/xudanu.git
cd xudanu
cargo build --features server -p xudanu

# Start the server
./target/debug/xudanu-server run 127.0.0.1:8080

# Open http://localhost:5173
# 1. Create a document with some text
# 2. Select a passage, click "Transclude"
# 3. Create another document
# 4. Place the transclusion in the new document
# 5. Edit the source — watch the transclusion update live

Further Reading

• GitHub repository — source, releases, and the FR design notes
• The Xanadu Network — cross-server trust, tumblers, federation
• Adversarial Resilience — how peer-supplied content is validated at the boundary
• Compound Documents — collections built from transclusions
• Provenance & Attribution — the cryptographic chain behind every quotation
• xudanu.com — live server; the Start Here trail walks through transclusion hands-on

Xudanu is an independent open-source project (Apache 2.0), not affiliated with Project Xanadu™ or the Udanax team. Transclusion concept © Ted Nelson. Udanax Gold released under X11 license (1999).