URI Resolution

Resolution is the process of converting a contextnest:// URI into a document or set of documents.

Floating resolution (default)

A URI without a checkpoint pin resolves to the latest published version:

contextnest://nodes/architecture
→ architecture v4 (current)

Pinned resolution

A URI with @N resolves to the version current at checkpoint N:

contextnest://nodes/architecture@5
→ architecture v2 (as of checkpoint 5)

The resolver reads .versions/context_history.yaml to look up the document_versions map at the specified checkpoint.

Source node resolution

When a URI targets a type: source node, resolution returns the source document itself (frontmatter and markdown body). Hydration — executing the described tool calls — is a separate step performed by the agent.

A link to a source node is a reference to the source's instructions and framing, not a guarantee that live data will be fetched.

Resolution order

1. Check the URI for an authority component (namespace). If present and federation is enabled, route to the external registry.
2. Normalize the URI to canonical form.
3. If pinned (@N), look up the version from the checkpoint history.
4. Resolve the path to a document, folder, tag set, or search result.
5. Return only published content (unless explicitly requesting drafts).