Xamidimura

Stable file snapshots and SHA-256 revisions for conflict-safe saves in Ruby applications

Installation · Quick start · Revision checks · Development

Xamidimura gives Canopus, Hadar, and Rukbat a shared way to observe a file's revision. It reads a stable byte snapshot, records a filesystem signature, and computes a SHA-256 digest. Each application remains responsible for its own reload and save-conflict policy.

gem install xamidimura

Requires Ruby 3.2 or newer. There are no runtime gem dependencies.

require "xamidimura"

path = "notes.md"
snapshot = Xamidimura::SourceRevision.read(path)

snapshot.bytes      # exact, frozen bytes read from disk
snapshot.signature  # frozen filesystem signature
snapshot.digest     # SHA-256 hex digest of those bytes

# Before saving, let the application decide what to do if the file changed.
if Xamidimura::SourceRevision.file_digest(path) != snapshot.digest
  warn "The file changed on disk"
end

read checks the file's signature before and after reading and retries when they differ (three attempts by default, configurable from one to ten). read and signature accept reject_symlink: true; file_digest follows symlinks.

• SourceRevision.signature(path) returns a filesystem signature for a cheap metadata comparison; it is not a content hash.
• SourceRevision.digest(bytes) hashes a String already in memory.
• SourceRevision.file_digest(path) hashes a file without loading it all into memory.

Comparing revisions can detect changes at that moment; it does not make a later write atomic. Applications choose how to handle a mismatch and protect their own saves. See ADR-001 for the deliberately narrow scope.

bundle install
bundle exec rake test
bundle exec rake rbs

The name Xamidimura comes from μ¹ Scorpii, an IAU-adopted Khoekhoe name derived from xami di mura, “eyes of the beast” (All Skies Encyclopaedia).

Xamidimura is released under the MIT License.