Strict no-heap RBKC validator and reader over named RA8 VFS mounts. More...

#include <stdint.h>
#include "book_chunked.h"
#include "ra8_c6link_mdl_transfer.h"
#include "ra8_io_vfs.h"

Include dependency graph for mdl_rabook_vfs.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	mdl_rabook_vfs_config_t
	Caller-owned decompression and strict-validation workspace binding. More...
struct	mdl_rabook_vfs_t
	One initialized strict validator or one open validated RBKC reader. More...

Functions
ra8_err_t	mdl_rabook_vfs_init (mdl_rabook_vfs_t ctx, const mdl_rabook_vfs_config_t config)
	Initialize one strict RBKC VFS workspace binding.
ra8_err_t	mdl_rabook_vfs_validate (void opaque, const char staging_path, uint64_t total_bytes, const uint8_t sha256[k_ra8_mdl_sha256_bytes])
	Strictly validate one closed private RBKC staging object.
ra8_err_t	mdl_rabook_vfs_open (mdl_rabook_vfs_t ctx, const char path)
	Open and strictly revalidate a published RBKC object for consumption.
ra8_err_t	mdl_rabook_vfs_read_chunk (mdl_rabook_vfs_t ctx, uint64_t offset, uint8_t dst, uint32_t len)
	Read one exact chunk-aligned flat-blob span from an open book.
ra8_err_t	mdl_rabook_vfs_info (const mdl_rabook_vfs_t ctx, book_header_t out_header, uint64_t *out_flat_size)
	Copy metadata from an open strictly validated book.
ra8_err_t	mdl_rabook_vfs_close (mdl_rabook_vfs_t *ctx)
	Close and release an open VFS reader facade.

Detailed Description

Strict no-heap RBKC validator and reader over named RA8 VFS mounts.

Tag: [Ring 4 / PAL] {World: NS}

Adapts the existing format-neutral ra8_io_vfs_file_t stream to the strict book_chunked_t reader. The same caller-owned workspace can be used as the artifact validator in mdl_storage_vfs_config_t and, after the transaction publishes, reopened on the final path for demand-paged reading. No file object is retained by validation; an open reader is retained only between mdl_rabook_vfs_open and mdl_rabook_vfs_close.

This module does not create a second filesystem facade. It only composes the existing VFS and book contracts and owns no heap, static workspace, mount, path, or publication policy.

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

Since: 0.1.0

Definition in file mdl_rabook_vfs.h.

Function Documentation

◆ mdl_rabook_vfs_close()

ra8_err_t mdl_rabook_vfs_close ( mdl_rabook_vfs_t * ctx )

nodiscard

Close and release an open VFS reader facade.

Parameters

[in,out] ctx Initialized context.

Returns: VFS close status, or success when already closed.

Precondition: No concurrent read uses ctx.

Postcondition: The context retains no file handle even when close reports an error.

Note: Does not unmount storage or modify the published file.

Since: 0.1.0

Definition at line 368 of file mdl_rabook_vfs.c.

References internal_rabook_close(), and k_ra8_err_null_ptr.

Referenced by internal_consume().

◆ mdl_rabook_vfs_info()

ra8_err_t mdl_rabook_vfs_info	(	const mdl_rabook_vfs_t *	ctx,
		book_header_t *	out_header,
		uint64_t *	out_flat_size )

nodiscard

Copy metadata from an open strictly validated book.

Parameters

[in]	ctx	Open validated context.
[out]	out_header	Receives the decoded flat RABOOK1 header.
[out]	out_flat_size	Receives the inflated flat-blob length.

Returns: Query status.

Return values

k_ra8_ok	Both outputs were initialized.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_state	No validated reader is open.

Precondition: No concurrent operation mutates ctx.

Postcondition: The open reader and file position are unchanged.

Since: 0.1.0

Definition at line 346 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_t::file, mdl_rabook_vfs_t::header, book_chunked_t::inflated_total, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, mdl_rabook_vfs_t::open, and mdl_rabook_vfs_t::reader.

Referenced by internal_consume().

◆ mdl_rabook_vfs_init()

ra8_err_t mdl_rabook_vfs_init	(	mdl_rabook_vfs_t *	ctx,
		const mdl_rabook_vfs_config_t *	config )

nodiscard

Initialize one strict RBKC VFS workspace binding.

Parameters

[out]	ctx	Caller-owned context.
[in]	config	Complete inflater and workspace descriptor.

Returns: Initialization status.

Return values

k_ra8_ok	The context is ready for validation or open.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_size	A workspace capacity is zero or table has fewer than two entries.

Precondition: No reader is open in ctx.

Postcondition: Success leaves ctx closed with no retained VFS facade.; Failure leaves ctx unchanged.

Note: Does not touch the VFS or inspect workspace contents.

Since: 0.1.0

Definition at line 207 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_config_t::chunk, mdl_rabook_vfs_config_t::chunk_cap, mdl_rabook_vfs_config_t::compressed, mdl_rabook_vfs_config_t::compressed_cap, mdl_rabook_vfs_config_t::inflate_cb, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, mdl_rabook_vfs_config_t::scratch, mdl_rabook_vfs_config_t::scratch_cap, mdl_rabook_vfs_config_t::table, and mdl_rabook_vfs_config_t::table_cap.

Referenced by internal_bind_transfer().

◆ mdl_rabook_vfs_open()

ra8_err_t mdl_rabook_vfs_open	(	mdl_rabook_vfs_t *	ctx,
		const char *	path )

nodiscard

Open and strictly revalidate a published RBKC object for consumption.

Parameters

[in,out]	ctx	Initialized closed context.
[in]	path	Named VFS path of the published .rabook.

Returns: Strict validation, VFS, or inflater status.

Return values

k_ra8_err_invalid_state A reader is already open.

Precondition: The selected mount remains registered until close.

Postcondition: Success retains one read-only VFS file and a strictly validated reader.; Failure retains no file facade and publishes no reader metadata.

Note: Revalidation prevents a stage-time verdict from authorizing changed bytes.

Since: 0.1.0

Definition at line 298 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_t::file, mdl_rabook_vfs_t::header, internal_rabook_close(), internal_rabook_open_reader(), internal_rabook_validate_open(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, and mdl_rabook_vfs_t::open.

Referenced by internal_consume().

◆ mdl_rabook_vfs_read_chunk()

ra8_err_t mdl_rabook_vfs_read_chunk	(	mdl_rabook_vfs_t *	ctx,
		uint64_t	offset,
		uint8_t *	dst,
		uint32_t	len )

nodiscard

Read one exact chunk-aligned flat-blob span from an open book.

Parameters

[in,out]	ctx	Open validated context.
[in]	offset	Chunk-aligned inflated-blob offset.
[out]	dst	Destination for exactly `len` bytes.
[in]	len	Exact inflated span for the selected chunk.

Returns: book_chunked_read status.

Precondition: mdl_rabook_vfs_open succeeded and the context remains exclusive.

Postcondition: Success initializes exactly len bytes in dst.

Since: 0.1.0

Definition at line 328 of file mdl_rabook_vfs.c.

References book_chunked_read(), mdl_rabook_vfs_t::file, k_ra8_err_invalid_state, k_ra8_err_null_ptr, mdl_rabook_vfs_t::open, and mdl_rabook_vfs_t::reader.

Referenced by internal_consume().

◆ mdl_rabook_vfs_validate()

ra8_err_t mdl_rabook_vfs_validate	(	void *	opaque,
		const char *	staging_path,
		uint64_t	total_bytes,
		const uint8_t	sha256[k_ra8_mdl_sha256_bytes] )

nodiscard

Strictly validate one closed private RBKC staging object.

Opens staging_path read-only, proves its exact size, validates every RBKC stream and the complete canonical RABOOK1 payload, then closes it. This signature directly satisfies mdl_storage_vfs_validate_fn.

Parameters

[in,out]	opaque	Initialized mdl_rabook_vfs_t.
[in]	staging_path	Named VFS path to the private closed artifact.
[in]	total_bytes	Independently verified transfer byte count.
[in]	sha256	Independently verified transfer digest.

Returns: Strict validation, VFS, inflater, or close status.

Precondition: The staging path remains immutable for the call.; No reader is open in opaque.

Postcondition: Success retains only decoded metadata and the digest, never a file handle.; Failure leaves the context closed and not transfer-validated.

Note: This function neither commits nor deletes the staging object.

Since: 0.1.0

Definition at line 257 of file mdl_rabook_vfs.c.

References mdl_rabook_vfs_t::digest, mdl_rabook_vfs_t::file, mdl_rabook_vfs_t::file_size, mdl_rabook_vfs_t::header, internal_rabook_close(), internal_rabook_open_reader(), internal_rabook_validate_open(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_mdl_sha256_bytes, k_ra8_ok, memcpy(), memset(), mdl_rabook_vfs_t::open, and mdl_rabook_vfs_t::transfer_validated.

Referenced by internal_bind_transfer().

Data Structures

Functions

Detailed Description

Function Documentation

◆ mdl_rabook_vfs_close()

◆ mdl_rabook_vfs_info()

◆ mdl_rabook_vfs_init()

◆ mdl_rabook_vfs_open()

◆ mdl_rabook_vfs_read_chunk()

◆ mdl_rabook_vfs_validate()