Module catalog 

The local block catalog: maps name@version to a cataloged wasm block or bundle, so a pipeline can reference a block by name instead of a filesystem path.

Storage is content-addressed and flat — no entry references another — because a bundle’s internal node structure lives entirely in its own .cfbundle manifest, resolved to concrete blob hashes at build time; the catalog index itself never needs to represent “this entry depends on that entry.”

~/.cuttlefish/catalog/
  blobs/<sha256>        raw wasm or bundle bytes, one copy per unique artifact
  index.json            name@version -> Entry
  index.json.lock       empty lock file guarding read-modify-write of index.json

See docs/superpowers/specs/2026-08-02-block-catalog-design.md for the full design (that file is a gitignored working document, not committed; this module doc is the durable record, per this project’s documentation-lives-in-the-code convention).

Structs

AddOutcome

What add actually did, for a caller to report.

Catalog

A local block catalog rooted at a directory. This type has no opinion about environment variables or home directories — the caller (the CLI) decides where root points.

Entry

One cataloged name@version.

Enums

ArtifactKind

Whether a cataloged artifact is a single wasm block, a multi-node bundle, or a Rhai script run by the shared interpreter.

CatalogError

Something went wrong reading, writing, or resolving through the catalog.

ResolutionContext

Where a pipeline entry string is being resolved from — determines whether an unqualified name (no @version) is legal. The dividing line is source-spec-text vs. compiled-artifact-reference, not “which command invoked it”: cuttlefish build resolves an unqualified name from the spec it was given exactly once, at build time, and records the exact resolution in the manifest it emits — the unqualified form itself never survives into that manifest.

Resolved

The result of resolving one pipeline entry string.

Functions

default_root

Where the catalog lives when the caller doesn’t say otherwise: $CUTTLEFISH_HOME/catalog if set, else ~/.cuttlefish/catalog. None when neither is available — see cuttlefish_home (private).

validate_block_name

Validate a cuttlefish block new name: must be legal as a Cargo crate-name component (so cf-block-<name> is always a valid package name for the Rust authoring path, even when a script is what actually gets scaffolded) and safe as a directory basename on every platform this project supports.