protocol

# `hash_state_protocol`

Protocol for hash functions supporting genuine incremental hash computation via an explicit, caller-driven hashing state. Unlike computing a hash from a single, fully materialized message, this protocol lets the caller feed the message to the hash function one chunk at a time (e.g. as each chunk is read from a file or a network stream), discarding each chunk as soon as it has been folded into the state. Only the current chunk and a small, bounded amount of algorithm state (for block-padded and rate-limited algorithms, a leftover buffer smaller than one block or rate) are ever resident at once, regardless of the total message length.

Availability:
`logtalk_load(hashes(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-07-16
Compilation flags:
`static`
Extends:
`public` hash_protocol
Remarks:
(none)
Inherited public predicates:
hash/2

## Public predicates

### `new_hash_state/1`

Creates a fresh hashing state, equivalent to having hashed the empty message so far. The state is an opaque, algorithm-specific term; callers should only pass it to update_hash_state/3 and final_hash_state/2, never inspect or construct it directly.

Compilation flags:
`static`
Template:
`new_hash_state(State)`
Mode and number of proofs:
`new_hash_state(--nonvar)` - `one`

### `update_hash_state/3`

Folds one chunk of bytes into a hashing state, returning the updated state. Can be called repeatedly, once per chunk, to fold in an arbitrarily long message without ever holding more than one chunk and the (bounded-size) state in memory at the same time. The chunks do not need to be the same length, and the empty chunk is allowed and is a no-op.

Compilation flags:
`static`
Template:
`update_hash_state(State,Bytes,NewState)`
Mode and number of proofs:
`update_hash_state(+nonvar,+list(byte),--nonvar)` - `one`

### `final_hash_state/2`

Finalizes a hashing state and returns the resulting hash, in the same representation as hash/2. The state must not be reused after finalization.

Compilation flags:
`static`
Template:
`final_hash_state(State,Hash)`
Mode and number of proofs:
`final_hash_state(+nonvar,--atom)` - `one`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

(no local declarations; see entity ancestors if any)

## Operators

(none)