Try Demo
Docs
GitHub
Join the beta
GitHubnpm
🗂bundleHash

bundleHash: LLM Bundle Hash

The bundleHash (prefixed with uifb:) tracks changes to an entire LLM context bundle, enabling efficient caching of embeddings and prepared contexts.

Purpose

Answers: "Has the entire context bundle changed?"

The bundleHash is used for caching embeddings and prepared LLM contexts. It provides a stable identifier that changes only when the semantic footprint of a bundle changes, making it ideal for cache invalidation and version tracking.

Use when: you need to determine if an LLM context bundle has changed semantically, allowing you to skip expensive embedding regeneration or context preparation when the bundle is unchanged.

Based On

A bundle's hash includes the following components:

Bundle Payload Structure

  • Sorted list of nodes (by entryId):
    • Each node contains: entryId and semanticHash
  • Bundle depth — the dependency traversal depth
  • Bundle schemaVersion (default "0.1")

Example payload:

{
  "schemaVersion": "0.1",
  "depth": 1,
  "nodes": [
    { "entryId": "src/Button.tsx", "semanticHash": "uif:..." },
    { "entryId": "src/Card.tsx",   "semanticHash": "uif:..." }
  ]
}

How It Is Computed

Computation Steps

  1. Build the bundle payload with schemaVersion, depth, and sorted nodes (by entryId).
  2. Stable-stringify the payload to ensure deterministic ordering.
  3. Compute SHA-256 hash of the stringified payload.
  4. Truncate to 24 hex characters.
  5. Prefix with uifb:.

Example: uifb:abc123e4f99aa01deef02bb1

Important: Nodes are sorted by entryId to ensure the hash is stable regardless of the order components are processed in memory.

What changes bundleHash

  • Any component's semanticHash changed
  • Adding/removing a component from the bundle
  • Different bundle depth
  • Different bundle schema version

What does not change it

  • Cosmetic file edits that keep all semanticHash values identical
  • Reordering components in memory (sorting by entryId ensures stability)

Relationship to Other Hashes

The bundleHash builds on top of semanticHash values from individual components:

Layer Hierarchy

File-level:fileHash→ detects any file content modification
Component-level:semanticHash→ detects logic & API changes
Bundle-level:bundleHash→ detects changes in bundle semantic footprint

Key insight: Since bundleHash depends on semanticHash values, any semantic change to a component will cascade up and change the bundle hash for all bundles containing that component.

Practical Scenarios

1. Only comments / formatting change in a component

  • fileHash: changes
  • semanticHash: stays the same
  • bundleHash: stays the same

→ Bundle cache remains valid, no need to regenerate embeddings.

2. A prop or state field is added to a component

  • fileHash: changes
  • semanticHash: changes
  • bundleHash: changes for all bundles involving that component

→ Bundle cache is invalidated, embeddings must be regenerated.

3. Dependency graph changes (component import added/removed)

  • semanticHash: may stay the same (if contracts are unchanged)
  • bundleHash: changes, because the node set changed

→ Bundle must be regenerated or recached for LLM use.

Hash Format

Bundle Hash (bundleHash)

  • Format: uifb: + 24 hex characters
  • Example: uifb:abc123e4f99aa01deef02bb1
  • Based on: Bundle structure (nodes sorted by entryId, depth, schema version)
  • Changes when: Any component's semantic hash changes, or bundle structure changes

See Hashes documentation for detailed information about all hash types and their relationships.