A complete program

The program

This program reads a file, hashes its content with blake3, and stores it in a content-addressed store at .store/<hex-hash>. It handles every failure case. It marks every side effect. It calls a C library without writing any C.

this program understands blake3

// blake3 face declarations
to begin a blake3 hash giving a hasher is blake3_hasher_init
    it gives back a hasher

to feed some bytes to a hasher is blake3_hasher_update
    it takes a hasher and some bytes

to finish a hasher giving some bytes is blake3_hasher_finalize
    it takes a hasher
    it gives back some bytes

// hash the contents of a file
to fingerprint, given the path:
    >> read the file at the path giving the contents
        but if it isn't there, say "file not found" and stop
        but if it can't be read, explain why and hand it on
    begin a blake3 hash giving the hasher
    feed the contents to the hasher
    finish the hasher giving the digest
    answer the digest

// write a hex string from bytes
to hex string from, given the bytes:
    the hex is ""
    for each byte in the bytes
        the hex is "{the hex}{the byte in hex}"
    answer the hex

// store the file content-addressed under .store/
to store, given the path:
    the digest is fingerprint the path
        but if it can't be read, explain why and stop
    the hex is hex string from the digest
    the dest is ".store/{the hex}"
    >> make the directory at ".store"
        but if it already exists, stop
        but if it can't be made, explain why and stop
    >> write the digest to the file at the dest
        but if it can't be written, explain why and stop
    >> say "stored {the path} as {the hex}"

// entry point
to begin:
    store "/notes/today.md"
        but if it can't be stored, give up

Line by line

The blake3 face (lines 1–12)

this program understands blake3 binds the library. The three face declarations describe the blake3 hasher API in Vision terms: begin initialises it, feed adds data, finish extracts the digest. No C code, no pointers.

fingerprint (lines 14–22)

Reads the file, handles two failure modes explicitly, then uses the begin/feed/finish pattern to produce a digest. Every >> line touches the world (the file read). The verb answers the raw digest bytes.

hex string from (lines 24–29)

Pure logic — no >> markers because this verb only manipulates values. It converts a list of bytes to a hex string by building up a text value.

store (lines 31–46)

Combines everything: fingerprints the file, derives a hex path, ensures the store directory exists, writes the digest, reports success. Notice that make the directory has two but if clauses — one for "already exists" (which is fine, just stop) and one for a genuine failure.

begin (lines 48–50)

The entry point calls store and handles its one possible failure with give up — if we cannot store the file, the program cannot continue, so this is a legitimate fatal exit.

What it shows

In about fifty lines of Vision, a program that would take several hundred lines of careful C — with manual error handling, buffer management, and careful null checking — is expressed clearly. Every failure is handled. Every side effect is marked. The C library is reached without writing C.

The result is code that can be read by someone who has never seen blake3, has never used Vision, and still understands what it does on the first pass. That is the promise.