jellycell.cache.hashing

Cache key derivation — the spec §10.2 contract.

The public surface here is tiny and frozen. Any change to normalization, input set, or composition requires the §10.2 ceremony:

  1. Bump :data:jellycell._version.MINOR_VERSION.

  2. Regenerate the regression snapshot in tests/unit/test_hashing.py.

  3. Add a CHANGELOG.md entry under [Unreleased] ### Changed.

See CLAUDE.md for the full rationale.

Module Contents

Functions

normalize_source

Normalize cell source text for stable hashing (spec §2.3).

source_hash

Hex sha256 of normalized source. Equivalent to the source component of the key.

env_hash_from_deps

Fallback env-hash: sha256 of sorted unique dep specifiers.

key

Derive the content-addressed cache key for a cell execution (spec §2.3).

API

jellycell.cache.hashing.normalize_source(source: str) → str

Normalize cell source text for stable hashing (spec §2.3).

  • Line endings → \n.

  • Per-line trailing whitespace stripped.

  • Leading/trailing blank lines removed.

  • Empty result returns empty string (no trailing newline).

jellycell.cache.hashing.source_hash(source: str) → str

Hex sha256 of normalized source. Equivalent to the source component of the key.

jellycell.cache.hashing.env_hash_from_deps(deps: collections.abc.Sequence[str]) → str

Fallback env-hash: sha256 of sorted unique dep specifiers.

Used when no lockfile hash is available. Callers that have a lockfile should hash the lockfile bytes directly.

jellycell.cache.hashing.key(*, source: str, dep_keys: collections.abc.Sequence[str], env_hash: str) → str

Derive the content-addressed cache key for a cell execution (spec §2.3).

Args: source: Raw cell source text; normalized internally. dep_keys: Cache keys of every cell this one depends on. Sorted internally so dep declaration order doesn’t affect the key. env_hash: Hash of the resolved environment (lockfile bytes, or :func:env_hash_from_deps fallback).

Returns: Lowercase hex sha256 digest.

Changing this function breaks spec §10.2. Follow the ceremony before editing.