@xemahq/distribution-source-hash

The canonical Xema source-tree content hash

Overview

This package belongs to Layer 1 — a framework-agnostic runtime SDK with zero dependencies, Node built-ins only. It executes git plumbing, so it is deliberately NOT part of @xemahq/distribution-resolver, which is pure (no IO, no clock).

It is the single implementation of xema-source-tree-sha256-v2, the algorithm behind a distribution image subject's contentHash. That hash is the release coordinate: producing CI tags the image <imageRef>:<contentHash>, and the distribution lock records the same value. A second implementation would split those two planes silently — every consumer therefore depends on this package instead of vendoring the algorithm.

When to use it

• Computing an image subject's contentHash in a producing repository's CI.
• Resolving or verifying a distribution's images.lock.json.
• Any deterministic read of an exact commit's source tree that must agree, byte for byte, with the value in a lock.

Installation

pnpm add @xemahq/distribution-source-hash

Usage

import {
  hashGitSourceTree,
  SourceTreeHashAlgorithm,
} from '@xemahq/distribution-source-hash';

const contentHash = hashGitSourceTree(
  '/path/to/repo',
  'biomes/knowledge-base/api/knowledge-base-api', // '.' hashes the whole repo
  '0123456789abcdef0123456789abcdef01234567', // exact 40-hex commit
  SourceTreeHashAlgorithm.MetadataV2,
);

Determinism contract

• Inputs are immutable Git objects read from an exact commit. The working tree, ignored build outputs, and machine-local files are never inputs.
• Entries are sorted with a locale-independent comparator and each field is length-framed (<label>\0 || uint64be(length) || bytes), so no two distinct trees can collapse onto the same digest.
• Paths are decoded as exact canonical UTF-8 and NFC-normalized.
• Build outputs and caches (node_modules, dist, .turbo, coverage, .git, openapi-fixture) are excluded.

Relationship to @xemahq/kernel-contracts

ImageSourceHashAlgorithm in @xemahq/kernel-contracts/distribution owns the algorithm's WIRE name — it is the sourceHashAlgorithm field of an ImageLock. This package owns the IMPLEMENTATION and declares SourceTreeHashAlgorithm itself, with the same values, so that a producing repository can derive its release tag from one dependency-free install and never couple its CI to a kernel contract version. The distribution tooling loads both built artifacts together and fails closed if the two ever stop naming the same algorithm.

Fail-fast behaviour

Every one of the following throws — there is no fallback and no silent skip:

• an algorithm other than the supported one;
• a commit that is not an exact 40-hex id, or does not exist;
• a source path that is empty, absolute, or traverses (..);
• a malformed ls-tree record, or an entry that is not a regular file or symlink blob;
• two entries whose paths collapse under NFC normalization;
• a source path that yields no hashable entries.

License

Apache-2.0 © Xema — xema.dev