Strict streaming-validation adapter for an open RBKC chunk reader. More...

#include <string.h>
#include "book_chunked.h"
#include "ra8_attributes.h"

Include dependency graph for book_chunked_validate.c:

Data Structures
struct	chunk_validate_t
	Cached inflated-chunk view used by arbitrary flat-source reads. More...

Enumerations
enum	chunk_validate_constant_t : uint8_t { k_chunk_validate_span_count = 5U }
	Fixed span count used by strict alias validation. More...

Functions
static bool	internal_spans_overlap (const void a, uint64_t a_len, const void b, uint64_t b_len, bool *invalid)
	Decide whether two non-empty caller-memory spans overlap.
static ra8_err_t	internal_validate_reader_fields (const book_chunked_t *rd)
	Require every reader callback and geometry field to be present.
static ra8_err_t	internal_validate_reader_table (const book_chunked_t *rd)
	Revalidate the derived chunk count and the offset table's shape.
static ra8_err_t	internal_validate_reader (const book_chunked_t *rd)
	Revalidate the open-reader invariants needed by strict validation.
static bool	internal_output_is_aliased (const book_chunked_t rd, const uint8_t chunk, uint32_t chunk_cap, const uint8_t scratch, uint32_t scratch_cap, const book_header_t out_header)
	Reject output aliases before the output is zeroed or published.
static ra8_err_t	internal_validate_workspaces (const book_chunked_t rd, const uint8_t chunk, uint32_t chunk_len, const uint8_t *scratch, uint32_t scratch_cap)
	Require strict-validation workspaces to be pairwise disjoint.
static ra8_err_t	internal_load_chunk (chunk_validate_t *ctx, uint32_t idx)
	Inflate one requested chunk into the caller cache when not resident.
static ra8_err_t	internal_chunk_flat_read (void opaque, uint64_t offset, uint8_t dst, uint32_t len)
	Serve an exact arbitrary flat-blob read through the one-chunk cache.
ra8_err_t	book_chunked_validate_strict (book_chunked_t rd, uint8_t chunk, uint32_t chunk_cap, uint8_t scratch, uint32_t scratch_cap, book_header_t out_header)
	Strictly validate the complete flat blob behind an open RBKC reader.

Detailed Description

Strict streaming-validation adapter for an open RBKC chunk reader.

Presents an opened chunk-compressed RBKC source as exact flat reads for the strict RABOOK1 validator. It rechecks reader geometry, rejects overlapping caller workspaces, inflates one chunk at a time, and retains no storage beyond the caller-owned reader, chunk, and validation scratch buffers.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: Version 0.1.0

Definition in file book_chunked_validate.c.

Enumeration Type Documentation

◆ chunk_validate_constant_t

enum chunk_validate_constant_t : uint8_t

Fixed span count used by strict alias validation.

Enumerator
k_chunk_validate_span_count	Reader, chunk, scratch, staging, and table.

Definition at line 30 of file book_chunked_validate.c.

Function Documentation

◆ book_chunked_validate_strict()

ra8_err_t book_chunked_validate_strict	(	book_chunked_t *	rd,
		uint8_t *	chunk,
		uint32_t	chunk_cap,
		uint8_t *	scratch,
		uint32_t	scratch_cap,
		book_header_t *	out_header )

nodiscard

Strictly validate the complete flat blob behind an open RBKC reader.

Adapts the chunk-aligned book_chunked_read interface to the random-read strict validator. chunk receives one complete inflated chunk at a time; scratch is the independent bounded CRC transfer and node-ownership workspace. The full-body pass requests every chunk, proving every compressed stream, its exact inflated length, and the inner RABOOK1 CRC without retaining the whole book.

Parameters

[in,out]	rd	Open chunk reader whose table is already validated.
[out]	chunk	Caller buffer for one inflated chunk.
[in]	chunk_cap	Capacity of `chunk`; must cover `rd->chunk_bytes`.
[out]	scratch	Caller transfer buffer for strict validation.
[in]	scratch_cap	Capacity of `scratch`; must be at least one byte and at least `ceil`(node_count/8) after header decode.
[out]	out_header	Receives the decoded header on success.

Returns: Validation status.

Return values

k_ra8_ok	Every RBKC stream and inner RABOOK1 field is valid.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_arg	Caller workspace spans overlap, including a detectable `out_header` alias.
k_ra8_err_invalid_state	`rd` is not open or its geometry/table is inconsistent.
k_ra8_err_invalid_size	A workspace or wire extent is inconsistent.
k_ra8_err_*	A file-reader, inflater, or strict-validator error.

Precondition: rd and its table remain alive and immutable; its staging is exclusively mutable.; chunk and scratch do not overlap each other or rd storage.; out_header does not overlap rd, the callback context reachable through rd->file_ctx, or any reader/caller workspace.

Postcondition: On success out_header describes the complete validated flat blob.; On failure out_header is zeroed and must not be consumed, provided the no-alias precondition holds. A detectable output alias is rejected without modifying the aliased storage.

Note: No heap allocation or recursion is used; the reader is not thread-safe.

Since: Version 0.1.0

Definition at line 401 of file book_chunked_validate.c.

References book_validate_stream_strict(), book_chunked_t::chunk_bytes, book_chunked_t::inflated_total, internal_chunk_flat_read(), internal_output_is_aliased(), internal_validate_reader(), internal_validate_workspaces(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_rabook_validate_open(), priv_mdl_verify_rabook(), and ra8_fmt_rabook_inspect_stream().

◆ internal_chunk_flat_read()

ra8_err_t internal_chunk_flat_read	(	void *	opaque,
		uint64_t	offset,
		uint8_t *	dst,
		uint32_t	len )

static

Serve an exact arbitrary flat-blob read through the one-chunk cache.

Splits a flat range at chunk boundaries, inflates each chunk at most once while resident, and copies until the exact request is met.

Parameters

[in,out]	opaque	Adapter context.
[in]	offset	Flat-blob byte offset.
[out]	dst	Destination for exactly `len` bytes.
[in]	len	Exact byte count.

Returns: Adapter, chunk-reader, or range status.

Return values

k_ra8_ok	Exactly `len` bytes were copied.
k_ra8_err_out_of_range	The requested flat range exceeds the source.

Precondition: Public validation established every pointer and workspace capacity.; opaque points to an initialized chunk-validation context.

Postcondition: Success fills all len destination bytes.; No bytes beyond the requested destination range are modified.

Note: Reads spanning chunk boundaries are copied iteratively without recursion.

Since: Version 0.1.0

Definition at line 374 of file book_chunked_validate.c.

References chunk_validate_t::chunk, book_chunked_t::chunk_bytes, book_chunked_t::inflated_total, internal_load_chunk(), k_ra8_err_out_of_range, k_ra8_ok, chunk_validate_t::loaded_len, memmove(), and chunk_validate_t::rd.

Referenced by book_chunked_validate_strict().

◆ internal_load_chunk()

ra8_err_t internal_load_chunk	(	chunk_validate_t *	ctx,
		uint32_t	idx )

static

Inflate one requested chunk into the caller cache when not resident.

Reuses an already resident matching chunk; otherwise derives the exact final-chunk length and delegates decompression to the reader.

Parameters

[in,out]	ctx	Adapter state.
[in]	idx	Chunk index to make resident.

Returns: Chunk-reader status.

Return values

k_ra8_ok	The requested chunk is resident in the caller cache.
k_ra8_err_out_of_range	The reader rejected the derived chunk range.

Precondition: idx is less than the open reader's chunk count.; ctx->chunk has capacity for the configured inflated chunk size.

Postcondition: Success makes idx and its exact span resident in ctx->chunk.; Failure does not mark the requested chunk as newly resident.

Note: Not thread-safe; reuses both reader staging and caller chunk storage.

Since: Version 0.1.0

Definition at line 334 of file book_chunked_validate.c.

References book_chunked_read(), chunk_validate_t::chunk, book_chunked_t::chunk_bytes, book_chunked_t::inflated_total, k_ra8_ok, chunk_validate_t::loaded, chunk_validate_t::loaded_idx, chunk_validate_t::loaded_len, and chunk_validate_t::rd.

Referenced by internal_chunk_flat_read().

◆ internal_output_is_aliased()

bool internal_output_is_aliased	(	const book_chunked_t *	rd,
		const uint8_t *	chunk,
		uint32_t	chunk_cap,
		const uint8_t *	scratch,
		uint32_t	scratch_cap,
		const book_header_t *	out_header )

static

Reject output aliases before the output is zeroed or published.

Compares the result object with the reader, inflated chunk, strict scratch, compressed staging, and offset-table spans fail-closed.

Parameters

[in]	rd	Candidate reader descriptor.
[in]	chunk	Inflated-chunk workspace, possibly NULL.
[in]	chunk_cap	Advertised `chunk` capacity.
[in]	scratch	Strict-validation workspace, possibly NULL.
[in]	scratch_cap	Advertised `scratch` capacity.
[out]	out_header	Candidate result storage.

Returns: Whether out_header overlaps a known reader or workspace span.

Return values

true	An overlap or unrepresentable span was found.
false	The result object is disjoint from every sized known span.

Precondition: rd and out_header are non-NULL and readable as their declared types.; Advertised capacities truthfully describe every non-NULL workspace.

Postcondition: No caller storage is read through an aliased pointer or modified.; A false result permits output clearing without corrupting known input.

Note: The opaque file callback context cannot be sized here and remains a documented caller no-alias precondition.

Since: Version 0.1.0

Definition at line 239 of file book_chunked_validate.c.

References internal_spans_overlap(), k_chunk_validate_span_count, book_chunked_t::staging, book_chunked_t::staging_cap, book_chunked_t::table, and book_chunked_t::table_cap_entries.

Referenced by book_chunked_validate_strict().

◆ internal_spans_overlap()

bool internal_spans_overlap	(	const void *	a,
		uint64_t	a_len,
		const void *	b,
		uint64_t	b_len,
		bool *	invalid )

static

Decide whether two non-empty caller-memory spans overlap.

Converts bases to integer addresses, proves each exclusive end is representable, then applies the standard half-open overlap test.

Parameters

[in]	a	First span base.
[in]	a_len	First span length in bytes.
[in]	b	Second span base.
[in]	b_len	Second span length in bytes.
[out]	invalid	Receives true when either end address would overflow.

Returns: Whether the two representable spans overlap.

Return values

true	The spans share at least one byte.
false	The spans are disjoint or an address range is invalid.

Precondition: Both span bases are non-NULL and lengths are non-zero.; invalid is non-NULL and writable.

Postcondition: invalid reports address-arithmetic overflow independently of overlap.; Input storage is not read or modified.

Note: Pure and thread-safe; comparisons use integer addresses to avoid undefined relational comparisons between unrelated C objects.

Since: Version 0.1.0

Definition at line 57 of file book_chunked_validate.c.

References memcpy().

Referenced by internal_output_is_aliased(), and internal_validate_workspaces().

◆ internal_validate_reader()

ra8_err_t internal_validate_reader ( const book_chunked_t * rd )

static

Revalidate the open-reader invariants needed by strict validation.

Recomputes chunk geometry, table bounds, monotonic compressed extents, and payload addition before any cache read is attempted.

Parameters

[in] rd Candidate open reader.

Returns: Reader-state validation status.

Return values

k_ra8_ok	Geometry, callbacks, table, and staging are usable.
k_ra8_err_invalid_state	The reader is partial or internally inconsistent.

Precondition: rd is non-NULL.; The table remains readable for chunk_count + 1 entries.

Postcondition: No reader or caller storage is modified.; Success proves every later table index and staging write is bounded.

Note: Pure and thread-safe for an immutable reader.

Since: Version 0.1.0

Definition at line 207 of file book_chunked_validate.c.

References internal_validate_reader_fields(), internal_validate_reader_table(), and k_ra8_ok.

Referenced by book_chunked_validate_strict().

◆ internal_validate_reader_fields()

ra8_err_t internal_validate_reader_fields ( const book_chunked_t * rd )

static

Require every reader callback and geometry field to be present.

Rejects a NULL file-read or inflate callback, a NULL table or staging buffer, and a zero chunk size, chunk count, inflated total, or staging capacity, before any arithmetic on those fields is attempted.

Parameters

[in] rd Candidate open reader.

Returns: Field-presence validation status.

Return values

k_ra8_ok	Every required callback and geometry field is present.
k_ra8_err_invalid_state	A required callback, buffer, or geometry field is NULL or zero.

Precondition: rd is non-NULL.; rd addresses a fully constructed reader, so each field read is initialized.

Postcondition: No reader or caller storage is modified.; Success proves the table pointer, staging buffer, and chunk divisor are usable.

Note: Pure and thread-safe for an immutable reader.

Since: Version 0.1.0

Definition at line 106 of file book_chunked_validate.c.

References book_chunked_t::chunk_bytes, book_chunked_t::chunk_count, book_chunked_t::file_read, book_chunked_t::inflate_cb, book_chunked_t::inflated_total, k_ra8_err_invalid_state, k_ra8_ok, book_chunked_t::staging, book_chunked_t::staging_cap, and book_chunked_t::table.

Referenced by internal_validate_reader().

◆ internal_validate_reader_table()

ra8_err_t internal_validate_reader_table ( const book_chunked_t * rd )

static

Revalidate the derived chunk count and the offset table's shape.

Recomputes the chunk count implied by inflated_total and chunk_bytes and requires it to match chunk_count exactly, requires the table to fit its declared capacity and start at zero, walks every entry to require strict monotonic increase bounded by the staging capacity, and requires the final payload offset addition not to overflow.

Parameters

[in] rd Candidate open reader whose field presence already passed internal_validate_reader_fields.

Returns: Table-shape validation status.

Return values

k_ra8_ok	The derived count matches and every table entry is sound.
k_ra8_err_invalid_state	The derived count, table bounds, or a table entry is inconsistent, or the payload offset addition overflows.

Precondition: rd is non-NULL.; rd->chunk_bytes, rd->chunk_count, rd->inflated_total, and rd->staging_cap are all non-zero.

Postcondition: No reader or caller storage is modified.; Success proves every later table index and staging write is bounded.

Note: Pure and thread-safe for an immutable reader.

Since: Version 0.1.0

Definition at line 158 of file book_chunked_validate.c.

References book_chunked_t::chunk_bytes, book_chunked_t::chunk_count, book_chunked_t::inflated_total, k_ra8_err_invalid_state, k_ra8_ok, book_chunked_t::payload_off, book_chunked_t::staging_cap, book_chunked_t::table, and book_chunked_t::table_cap_entries.

Referenced by internal_validate_reader().

◆ internal_validate_workspaces()

ra8_err_t internal_validate_workspaces	(	const book_chunked_t *	rd,
		const uint8_t *	chunk,
		uint32_t	chunk_len,
		const uint8_t *	scratch,
		uint32_t	scratch_cap )

static

Require strict-validation workspaces to be pairwise disjoint.

Checks every pair among the reader, inflated chunk, semantic scratch, compressed staging, and exact validated table spans.

Parameters

[in]	rd	Validated open reader.
[in]	chunk	Inflated-chunk workspace.
[in]	chunk_len	Bytes of `chunk` the adapter will access.
[in]	scratch	Semantic and CRC workspace.
[in]	scratch_cap	Writable bytes at `scratch`.

Returns: Workspace validation status.

Return values

k_ra8_ok	All five mutable/read-only workspace spans are disjoint.
k_ra8_err_invalid_arg	Spans overlap or address arithmetic overflows.

Precondition: All bases are non-NULL and lengths are non-zero.; Reader geometry and table bounds passed internal_validate_reader.

Postcondition: No workspace bytes are modified.; Success prevents cache corruption through caller-buffer aliasing.

Note: Pure and thread-safe for immutable span descriptors.

Since: Version 0.1.0

Definition at line 290 of file book_chunked_validate.c.

References book_chunked_t::chunk_count, internal_spans_overlap(), k_chunk_validate_span_count, k_ra8_err_invalid_arg, k_ra8_ok, book_chunked_t::staging, book_chunked_t::staging_cap, and book_chunked_t::table.

Referenced by book_chunked_validate_strict().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ chunk_validate_constant_t

Function Documentation

◆ book_chunked_validate_strict()

◆ internal_chunk_flat_read()

◆ internal_load_chunk()

◆ internal_output_is_aliased()

◆ internal_spans_overlap()

◆ internal_validate_reader()

◆ internal_validate_reader_fields()

◆ internal_validate_reader_table()

◆ internal_validate_workspaces()