Module blockchain_kind 

Foundation for KIND blockchain collections (issue #523).

Persists kind in red_config, exposes the reserved-column set used by every block row, scans the collection to derive the current chain tip, and wraps the hash helpers from crate::storage::blockchain.

This iteration does NOT validate user-supplied prev_hash/height on INSERT (the engine computes them) and does NOT enforce conflict-retry semantics — those land alongside chain-tip RPC and verify_chain in a later slice.

Structs

ChainTip

Chain tip derived by scanning the collection.

ChainTipFull

Full chain tip including timestamp. Returned by chain_tip_full and GET /collections/:name/chain-tip.

VerifyChainOutcome

Outcome of POST /collections/:name/verify-chain.

Constants

CHAIN_KIND_TAG

Value stored under red.collection.{name}.kind for blockchain collections.

COL_BLOCK_HEIGHT

COL_HASH

COL_PREV_HASH

COL_TIMESTAMP

RESERVED_COLUMNS

Reserved column names auto-filled by the engine; user INSERTs that supply them are silently overwritten so the chain remains engine-controlled.

Functions

canonical_payload

Canonicalize user-supplied fields for inclusion in the block hash. Sorted by key, <key>=<plain_text>; joined — stable across reorderings so the recomputed hash matches regardless of column order at INSERT-time.

chain_conflict_error

Build the BlockchainConflict:<json> error payload mapped to HTTP 409 (#524). The JSON body carries the current tip so the caller can retry with the right prev_hash / block_height.

chain_tip

Scan the collection for the highest block_height and return its row’s hash. O(n) — replaced by a cached tip in a later iteration.

chain_tip_full

Scan-based tip with timestamp. None when the collection has no rows (pre-genesis). Used by the chain-tip endpoint and the chain-INSERT validation path (#524).

collect_blocks

Issue #525 — walk a chain collection in block_height order and rebuild the Block list expected by verify_chain. Genesis is identified by block_height == 0. Returns None when the collection is absent or not a chain. Reserved-column extraction and canonical payload encoding mirror what the engine writes at INSERT time — this is the alignment of the two encoders referenced in #524.

genesis_fields

Convenience: produce the genesis row’s full field list. Genesis carries an empty user payload — extra metadata is recorded in subsequent blocks.

is_chain

True if mark_as_chain was ever called for this collection.

is_integrity_broken_persisted

Scan red_config for the latest persisted integrity flag for collection. None means no record (treated as ok).

make_block_reserved_fields

Build the reserved-column key/value pairs for a new block. Caller appends these to the row’s fields AFTER stripping any user-supplied reserved columns. The returned hash is also returned so callers can advance the tip without recomputing.

mark_as_chain

Persist the chain kind marker. Append-only — only call once at creation.

now_ms

persist_integrity_flag

Persist a chain’s integrity flag in red_config. Append-only — readers use is_integrity_broken_persisted which picks the latest matching row by id.

verify_chain_outcome

Walk the chain end-to-end. Returns (outcome, _). Mismatches are detected via verify_chain. Callers persist the integrity flag on ok == false.