# Class BSV::Overlay::Historian <a id="class-BSV-Overlay-Historian"></a>

**Inherits:** `Object`

Builds a chronological history (oldest → newest) of typed values by traversing
a transaction's input ancestry and interpreting each output with a provided
interpreter.

The interpreter contract is: +interpreter.call(tx, output_index, ctx)+,
returning the typed value or `nil`. Any callable responding to
<code>:call</code> is accepted (lambda, proc, method, or object).

Traversal follows <code>input.source_transaction</code> references
recursively. Callers must supply transactions whose inputs have
`source_transaction` populated.

## Cycle safety

Each transaction is visited at most once, tracked by its `wtxid` (wire-order
binary).

## Value semantics

Only `nil` is excluded. Falsy non-nil values (`false`, +""+, `0`) are valid
history entries and are included in the result.

## Caching

An optional `history_cache` (any <code>[]/[]=</code> responder) caches
complete history results. Cache keys have the form:
<code>"#{interpreter_version}|#{dtxid_hex}|#{ctx_key}"</code>. Cached arrays
are stored frozen; each retrieval returns a `dup` to protect the cache.

## Note

The Ruby Historian is synchronous. There is no async/await semantics.

## Public Instance Methods
### `build_history(start_transaction, context = nil)` <a id="method-i-build_history"></a> <a id="build_history-instance_method"></a>
Traverses input ancestry from `start_transaction` and returns all interpreted
values in chronological order (oldest first).
- **@param** `start_transaction` [Transaction::Tx]
- **@param** `context` [Object, nil] forwarded verbatim to the interpreter
- **@return** [Array] interpreted values, oldest first

### `initialize(interpreter, debug: = false, history_cache: = nil, interpreter_version: = 'v1', ctx_key_fn: = nil)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
- **@param** `interpreter` [#call] callable: +call(tx, output_index, ctx) → value|nil+
- **@param** `debug` [Boolean] enable debug logging via +BSV.logger+
- **@param** `history_cache` [Hash, nil] optional cache store (+[]/[]=+ responder)
- **@param** `interpreter_version` [String] version tag for cache key invalidation
- **@param** `ctx_key_fn` [#call, nil] serialises context to a string cache key
- **@return** [Historian] a new instance of Historian