Try Demo
Docs
GitHub
Join the beta
GitHubnpm
🔐Hashes

Hashes in LogicStamp

LogicStamp uses three complementary hash types to track file changes, semantic changes, and bundle-level changes:fileHash, semanticHash, and bundleHash.

📄 fileHash: Raw File Content Hash

Answers: “Did the raw source file change?”

fileHash is a hash of the normalized file contents and is used as a lock to ensure that a stored contract still reflects the actual file on disk.

How it is computed

  1. Take the raw file contents.
  2. Strip the @uif metadata header block.
  3. Normalize line endings (\r\n → \n).
  4. SHA-256 hash the text.
  5. Truncate to 24 hex characters.
  6. Prefix with uif:.

Example: uif:1f0fa0e2c8958d7fc1696036

What changes / does not change it

Changes fileHash

  • Any code change
  • Comment changes
  • Formatting or whitespace changes
  • Structural edits
  • Line ending differences (after normalization)

Does not change fileHash

  • Editing only the @uif header
  • Purely changing metadata outside the hashed body

Use when: you want strict detection of any file content modification, even if it is purely cosmetic.

🧠 semanticHash: Logical / Contract Hash

Answers: “Did the component’s semantics or public API change?”

semanticHash tracks meaningful changes only—ignoring superficial edits like comments or formatting.

Based on AST structure and logic signature

LogicStamp derives semanticHash from:

  • Structural footprint:
    • variables
    • hooks
    • components
    • functions
  • Logic signature:
    • props
    • emits/events
    • state
  • A stable schemaVersion (e.g., "0.3").

All arrays/objects are sorted deterministically via stableStringify and sortObject to make the hash order-independent.

How it is computed

  1. Extract AST structure and logic signature.
  2. Build payload:
{
  "schemaVersion": "0.3",
  "structure": { "...": "..." },
  "signature": { "...": "..." }
}
  1. Stable-stringify the payload and compute SHA-256.
  2. Truncate to 24 hex characters.
  3. Prefix with uif:.

What changes semanticHash

  • Adding/removing/renaming props
  • Changing events (emits)
  • Changing state structure
  • Adding/removing named functions, hooks, or child components
  • Any structural AST shift that affects the contract shape

What does not change it

  • Comments
  • Whitespace or formatting
  • Most implementation details inside functions
  • Internal refactors that do not affect:
    • props
    • events
    • state
    • component/hook/function footprint

🗂 bundleHash: LLM Bundle Hash

Answers: “Has the entire context bundle changed?”

bundleHash is used for caching embeddings and prepared LLM contexts. It summarizes the semantic footprint of an entire bundle.

Based on

A bundle’s hash includes:

  • Sorted list of nodes (by entryId):
{
  "schemaVersion": "0.1",
  "depth": 1,
  "nodes": [
    { "entryId": "src/Button.tsx", "semanticHash": "uif:..." },
    { "entryId": "src/Card.tsx",   "semanticHash": "uif:..." }
  ]
}
  • Bundle depth
  • Bundle schemaVersion (default "0.1")

How it is computed

  1. Build the bundle payload (schemaVersion, depth, sorted nodes).
  2. Stable-stringify the payload.
  3. Compute SHA-256.
  4. Truncate to 24 hex characters.
  5. Prefix with uifb:.

Example: uifb:abc123e4f99aa01deef02bb1

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 Between All Three Hashes

Think of the three hashes as layers of change detection:

LayerHashDetects
File-levelfileHashAny file content modification
Component-levelsemanticHashLogic & public API changes only
Bundle-levelbundleHashChanges in the semantic footprint of a context bundle

🔎 Practical Scenarios

1. Only comments / formatting change

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

→ Cosmetic edit.

2. A prop or state field is added

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

→ Meaningful contract change.

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.