ra8_fmt_stream.h File Reference

Caller-workspace I/O contracts for portable format-tool engines. More...

#include <stddef.h>
#include <stdint.h>
#include "jof.h"
#include "jof_audit.h"
#include "ra8_err.h"

Include dependency graph for ra8_fmt_stream.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_fmt_source_t
	Immutable, randomly readable input object. More...
struct	ra8_fmt_sink_t
	Injected append-only sink. More...
struct	ra8_fmt_spool_t
	Caller-owned scratch artifact with append, seal, and read seams. More...
struct	ra8_fmt_transaction_ops_t
	Durable artifact-transaction operations. More...
struct	ra8_fmt_transaction_t
	One caller-owned artifact transaction. More...
struct	ra8_fmt_jof_convert_requirements_t
	Source geometry and exact arenas required by one JOF conversion. More...
struct	ra8_fmt_jof_convert_workspace_t
	Caller-owned arenas supplied to the streaming JOF converter. More...
struct	ra8_fmt_jof_verify_requirements_t
	Exact phase-reused storage requirements for JOF verification. More...
struct	ra8_fmt_jof_verify_workspace_t
	Caller-owned phase-overlaid arenas for one bounded JOF verification. More...
struct	ra8_fmt_jof_inspect_workspace_t
	Exact caller-owned storage used by streaming JOF inspection. More...
struct	ra8_fmt_rabook_inspect_workspace_t
	Caller-owned storage for strict streamed RBKC/RABOOK1 inspection. More...

Typedefs
typedef ra8_err_t(*	ra8_fmt_source_validate_fn) (void *ctx, uint64_t expected_size)
	Revalidate one positioned source against its captured immutable view.
typedef ra8_err_t(*	ra8_fmt_sink_write_fn) (void *ctx, const uint8_t *bytes, size_t len)
	Append text or binary bytes to a bounded backend.
typedef ra8_err_t(*	ra8_fmt_spool_seal_fn) (void *ctx, uint64_t expected_size)
	Seal an exact scratch artifact for immutable positioned reads.

Functions
ra8_err_t	ra8_fmt_jof_inspect_stream (const ra8_fmt_source_t *source, bool verbose, const ra8_fmt_jof_inspect_workspace_t *workspace, const ra8_fmt_sink_t *report)
	Inspect one JOF source through callbacks and caller storage.
ra8_err_t	ra8_fmt_rabook_inspect_stream (const ra8_fmt_source_t *source, bool verbose, ra8_fmt_rabook_inspect_workspace_t *workspace, const ra8_fmt_sink_t *report)
	Strictly inspect one streamed RBKC container and its RABOOK1 payload.
ra8_err_t	ra8_fmt_jof_convert_requirements (const ra8_fmt_source_t *source, ra8_fmt_jof_convert_requirements_t *out)
	Derive source geometry and exact JOF conversion workspace needs.
ra8_err_t	ra8_fmt_jof_convert_stream (const ra8_fmt_source_t *source, const ra8_fmt_jof_convert_requirements_t *requirements, const ra8_fmt_jof_convert_workspace_t *workspace, ra8_fmt_transaction_t *transaction, const ra8_fmt_sink_t *report, const char *output_name)
	Stream one encoded image into a durably published JOF artifact.
ra8_err_t	ra8_fmt_jof_verify_requirements (const ra8_fmt_source_t *source, ra8_fmt_jof_verify_requirements_t *out)
	Derive exact producer and comparison storage for bounded JOF verification.
ra8_err_t	ra8_fmt_jof_verify_stream (const ra8_fmt_source_t *reference_source, const ra8_fmt_source_t *banded_source, const ra8_fmt_jof_verify_requirements_t *requirements, ra8_fmt_jof_verify_workspace_t *workspace, ra8_fmt_spool_t *reference_spool, ra8_fmt_spool_t *banded_spool, ra8_fmt_transaction_t *dump, const char *dump_name, const ra8_fmt_sink_t *report)
	Verify banded JOF pixels against an independently decoded row reference.

Detailed Description

Caller-workspace I/O contracts for portable format-tool engines.

Tag

[Ring 4 / Domain] {World: NS}

Format engines depend only on positioned input, append-only artifact output, durable transaction control, and an injected text sink. Host file descriptors, firmware VFS streams, and in-memory tests bind the same contracts.

Copyright

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

Since

0.1.0

Definition in file ra8_fmt_stream.h.

Typedef Documentation

ra8_fmt_sink_write_fn

typedef ra8_err_t(* ra8_fmt_sink_write_fn) (void *ctx, const uint8_t *bytes, size_t len)

Append text or binary bytes to a bounded backend.

Definition at line 42 of file ra8_fmt_stream.h.

ra8_fmt_source_validate_fn

typedef ra8_err_t(* ra8_fmt_source_validate_fn) (void *ctx, uint64_t expected_size)

Revalidate one positioned source against its captured immutable view.

Definition at line 31 of file ra8_fmt_stream.h.

ra8_fmt_spool_seal_fn

typedef ra8_err_t(* ra8_fmt_spool_seal_fn) (void *ctx, uint64_t expected_size)

Seal an exact scratch artifact for immutable positioned reads.

Definition at line 51 of file ra8_fmt_stream.h.

Function Documentation

ra8_fmt_jof_convert_requirements()

ra8_err_t ra8_fmt_jof_convert_requirements ( const ra8_fmt_source_t * source, ra8_fmt_jof_convert_requirements_t * out )

nodiscard

Derive source geometry and exact JOF conversion workspace needs.

Parameters

[in]	source	Immutable JPEG, PNG, or WebP input.
[out]	out	Receives exact arena requirements and chosen band geometry.

Returns

Probe or sizing status.

Return values

k_ra8_ok	Requirements are complete and non-zero where applicable.
k_ra8_err_not_supported	Source is not a supported baseline image.
k_ra8_err_invalid_size	Geometry, source length, or arena sizing is invalid.

Precondition

source provides a stable positioned-read callback for source->size bytes.

out is writable.

Postcondition

Success initializes every field of out.

No source byte or backend position is changed.

Note

Thread-safe for independent source contexts and caller workspaces.

Since

0.1.0

Definition at line 615 of file ra8_fmt_stream_convert.c.

References ra8_fmt_jof_convert_requirements_t::height, internal_probe(), jof_webp_work_bytes(), jof_work_bytes(), k_convert_band_height, k_convert_kind_jpeg, k_convert_kind_webp, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_fmt_source_t::read_at, ra8_fmt_source_t::size, ra8_fmt_jof_convert_requirements_t::tile_height, ra8_fmt_jof_convert_requirements_t::tile_width, ra8_fmt_jof_convert_requirements_t::webp_work_bytes, ra8_fmt_jof_convert_requirements_t::width, and ra8_fmt_jof_convert_requirements_t::work_bytes.

Referenced by internal_size_input(), and ra8_fmt_jof_verify_requirements().

ra8_fmt_jof_convert_stream()

ra8_err_t ra8_fmt_jof_convert_stream ( const ra8_fmt_source_t * source, const ra8_fmt_jof_convert_requirements_t * requirements, const ra8_fmt_jof_convert_workspace_t * workspace, ra8_fmt_transaction_t * transaction, const ra8_fmt_sink_t * report, const char * output_name )

nodiscard

Stream one encoded image into a durably published JOF artifact.

Parameters

[in]	source	Immutable JPEG, PNG, or WebP input.
[in]	requirements	Exact requirements derived for source.
[in,out]	workspace	Caller-owned exact-or-larger producer arenas.
[in,out]	transaction	Active append-only durable output transaction.
[in,out]	report	Human-readable report sink.
[in]	output_name	Stable destination spelling for the report.

Returns

Producer, transaction, or report status.

Return values

k_ra8_ok	Complete atlas was durably committed and reported.
k_ra8_err_invalid_size	A supplied arena is below its exact requirement.

Precondition

requirements came from ra8_fmt_jof_convert_requirements for source.

transaction owns an unpublished sibling stage.

Postcondition

Success commits exactly one complete JOF artifact.

Any pre-commit failure aborts the stage and preserves the prior destination.

Note

Performs no allocation and retains no caller pointer.

Since

0.1.0

Definition at line 646 of file ra8_fmt_stream_convert.c.

References ra8_fmt_transaction_ops_t::abort, ra8_fmt_transaction_ops_t::append, ra8_fmt_transaction_ops_t::commit, ra8_fmt_transaction_t::ctx, ra8_fmt_jof_convert_requirements_t::height, internal_abort(), internal_append(), internal_pull(), internal_report(), jof_produce(), k_jof_codec_deflate, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_fmt_transaction_t::ops, ra8_fmt_source_t::read_at, ra8_fmt_jof_convert_requirements_t::tile_height, ra8_fmt_jof_convert_requirements_t::tile_width, ra8_fmt_jof_convert_workspace_t::webp_work, ra8_fmt_jof_convert_requirements_t::webp_work_bytes, ra8_fmt_jof_convert_workspace_t::webp_work_cap, ra8_fmt_jof_convert_requirements_t::width, ra8_fmt_jof_convert_requirements_t::work_bytes, and ra8_fmt_jof_convert_workspace_t::work_cap.

Referenced by internal_run().

ra8_fmt_jof_inspect_stream()

ra8_err_t ra8_fmt_jof_inspect_stream ( const ra8_fmt_source_t * source, bool verbose, const ra8_fmt_jof_inspect_workspace_t * workspace, const ra8_fmt_sink_t * report )

nodiscard

Inspect one JOF source through callbacks and caller storage.

Parameters

[in]	source	Immutable JOF input.
[in]	verbose	Emit header/footer hex and the full tile table.
[in,out]	workspace	Exact-or-larger audit buffers.
[in,out]	report	Human-readable text sink.

Returns

Audit or sink status.

Postcondition

No allocation occurs and no backend pointer is retained.

Since

0.1.0

Definition at line 584 of file ra8_fmt_stream_inspect.c.

References ra8_fmt_source_t::ctx, jof_audit_result_t::duplicate_candidates, jof_audit_result_t::info, internal_geometry(), internal_hex_dump(), internal_table(), internal_text(), internal_value_line(), jof_audit(), k_jof_footer_bytes, k_jof_hdr_bytes, k_ra8_err_null_ptr, k_ra8_err_validation_failed, k_ra8_ok, ra8_fmt_source_t::read_at, ra8_fmt_jof_inspect_workspace_t::record_cap, ra8_fmt_jof_inspect_workspace_t::records, ra8_fmt_jof_inspect_workspace_t::scratch, ra8_fmt_jof_inspect_workspace_t::scratch_cap, ra8_fmt_source_t::size, ra8_fmt_jof_inspect_workspace_t::tile, ra8_fmt_jof_inspect_workspace_t::tile_cap, and jof_info_t::tile_count.

Referenced by internal_run_jof().

ra8_fmt_jof_verify_requirements()

ra8_err_t ra8_fmt_jof_verify_requirements ( const ra8_fmt_source_t * source, ra8_fmt_jof_verify_requirements_t * out )

nodiscard

Derive exact producer and comparison storage for bounded JOF verification.

Parameters

[in]	source	Stable JPEG, PNG, or WebP source.
[out]	out	Receives exact phase requirements.

Returns

Probe or sizing status.

Precondition

source provides immutable positioned reads for its declared size.

Postcondition

Success initializes every requirement field without creating a spool.

Note

Source-kind parsing is bounded by source size and caller storage.

Since

0.1.0

Definition at line 341 of file ra8_fmt_stream_verify_plan.c.

References ra8_fmt_jof_verify_requirements_t::band_height, ra8_fmt_jof_verify_requirements_t::band_tile_bytes, ra8_fmt_jof_verify_requirements_t::banded_work_bytes, ra8_fmt_jof_verify_requirements_t::bpp, ra8_fmt_jof_convert_requirements_t::height, ra8_fmt_jof_verify_requirements_t::height, internal_bpp(), internal_stable(), jof_stored_bound(), jof_work_bytes(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_fmt_jof_convert_requirements(), ra8_fmt_source_t::read_at, ra8_fmt_jof_verify_requirements_t::reference_work_bytes, ra8_fmt_jof_verify_requirements_t::row_bytes, ra8_fmt_jof_verify_requirements_t::scratch_bytes, ra8_fmt_jof_convert_requirements_t::tile_height, ra8_fmt_jof_convert_requirements_t::webp_work_bytes, ra8_fmt_jof_verify_requirements_t::webp_work_bytes, ra8_fmt_jof_convert_requirements_t::width, ra8_fmt_jof_verify_requirements_t::width, and ra8_fmt_jof_convert_requirements_t::work_bytes.

Referenced by internal_open_and_size().

ra8_fmt_jof_verify_stream()

ra8_err_t ra8_fmt_jof_verify_stream ( const ra8_fmt_source_t * reference_source, const ra8_fmt_source_t * banded_source, const ra8_fmt_jof_verify_requirements_t * requirements, ra8_fmt_jof_verify_workspace_t * workspace, ra8_fmt_spool_t * reference_spool, ra8_fmt_spool_t * banded_spool, ra8_fmt_transaction_t * dump, const char * dump_name, const ra8_fmt_sink_t * report )

nodiscard

Verify banded JOF pixels against an independently decoded row reference.

Encodes two independent source contexts into sealed scratch atlases: one-row reference tiles remove inter-row band accumulation, while 256-row subject tiles exercise the production band path. Tiles are decoded and compared one row at a time; an optional PPM is transactionally published.

Parameters

[in]	reference_source	First immutable encoded-source context.
[in]	banded_source	Independent context for the same encoded object.
[in]	requirements	Exact requirements derived for the source.
[in,out]	workspace	Caller-owned phase-reused arenas.
[in,out]	reference_spool	Empty scratch artifact for reference JOF bytes.
[in,out]	banded_spool	Empty scratch artifact for subject JOF bytes.
[in,out]	dump	Optional durable PPM transaction; null disables the dump.
[in]	dump_name	Destination spelling used in the legacy report line.
[in,out]	report	Human-readable raw byte sink.

Returns

Exact-verdict, validation, producer, spool, or source status.

Return values

k_ra8_ok	Every compared byte matched.
k_ra8_err_validation_failed	At least one raster byte differed.

Precondition

Source contexts are distinct, stable views of one encoded object.

Spools are empty and their callbacks remain bound for the call.

Workspace capacities meet requirements; phase-overlap is permitted.

Postcondition

Success sealed both spools and compared the complete decoded raster.

An enabled dump is committed on successful reconstruction even when pixels differ, matching the legacy diagnostic-dump behavior.

Any dump write failure aborts its stage and does not change the verdict.

Note

No dynamic storage, formatted stream, hidden singleton, or whole raster is used.

Since

0.1.0

Definition at line 913 of file ra8_fmt_stream_verify.c.

References ra8_fmt_transaction_ops_t::abort, ra8_fmt_transaction_ops_t::append, verify_atlases_t::banded, ra8_fmt_transaction_ops_t::commit, internal_abort_dump(), internal_abort_transaction(), internal_check(), internal_compare(), internal_finish_dump(), internal_geometry(), internal_prepare(), internal_stable(), internal_verdict(), k_ra8_err_null_ptr, k_ra8_err_validation_failed, k_ra8_ok, ra8_fmt_transaction_t::ops, and verify_atlases_t::reference.

Referenced by internal_run().

ra8_fmt_rabook_inspect_stream()

ra8_err_t ra8_fmt_rabook_inspect_stream ( const ra8_fmt_source_t * source, bool verbose, ra8_fmt_rabook_inspect_workspace_t * workspace, const ra8_fmt_sink_t * report )

nodiscard

Strictly inspect one streamed RBKC container and its RABOOK1 payload.

Parameters

[in]	source	Immutable positioned container source.
[in]	verbose	Emit the bounded chunk inventory.
[in,out]	workspace	Exact-or-larger table and validator buffers.
[in,out]	report	Human-readable injected text sink.

Returns

Container, decompression, inner-validation, or sink status.

Precondition

All workspace spans are disjoint and remain live for the call.

Postcondition

Every compressed stream and every inner reference has been validated on success; no source pointer or workspace pointer is retained.

Since

0.1.0

Definition at line 352 of file ra8_fmt_stream_rabook.c.

References book_chunked_open(), book_chunked_validate_strict(), ra8_fmt_rabook_inspect_workspace_t::chunk, ra8_fmt_rabook_inspect_workspace_t::chunk_cap, ra8_fmt_rabook_inspect_workspace_t::compressed, ra8_fmt_rabook_inspect_workspace_t::compressed_cap, ra8_fmt_source_t::ctx, internal_exact_read(), internal_inflate(), internal_report(), internal_text(), k_ra8_err_null_ptr, k_ra8_ok, ra8_fmt_source_t::read_at, ra8_fmt_rabook_inspect_workspace_t::scratch, ra8_fmt_rabook_inspect_workspace_t::scratch_cap, ra8_fmt_source_t::size, ra8_fmt_rabook_inspect_workspace_t::table, ra8_fmt_rabook_inspect_workspace_t::table_cap, and ra8_fmt_source_t::validate.

Referenced by internal_run_rabook().