ra8_fmt_stream_verify.c File Reference

Caller-workspace two-spool JOF round-trip verification. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "jof_produce.h"
#include "ra8_attributes.h"
#include "ra8_fmt_stream.h"

Include dependency graph for ra8_fmt_stream_verify.c:

Go to the source code of this file.

Data Structures
struct	verify_pull_t
	Sequential cursor over one positioned source context. More...
struct	verify_compare_t
	Comparison state shared by bounded tile/row helpers. More...
struct	verify_atlases_t
	Parsed and fully preflighted reference and subject atlases. More...

Enumerations
enum	verify_const_t : uint32_t {   k_verify_band_height = 256U ,   k_verify_diffs_max = 8U ,   k_verify_decimal_max = 20U ,   k_verify_decimal = 10U ,   k_verify_hex_radix = 16U ,   k_verify_ppm_max_text = 5U }
	Verification geometry, report, and probe constants. More...

Functions
static ra8_err_t	internal_stable (const ra8_fmt_source_t *source)
	Validate a source through its optional stability callback.
static ra8_err_t	internal_pull (void *ctx, uint8_t *bytes, size_t cap, size_t *got)
	Pull the next bounded source prefix for streamed JOF production.
static ra8_err_t	internal_spool_append (void *ctx, const uint8_t *bytes, size_t len)
	Append one produced JOF span to the injected verifier spool.
static ra8_err_t	internal_produce (const ra8_fmt_source_t *source, const ra8_fmt_jof_verify_requirements_t *need, uint16_t tile_h, ra8_fmt_jof_verify_workspace_t *work, ra8_fmt_spool_t *spool, jof_info_t *info)
	Produce and seal one deflate JOF into an injected spool.
static ra8_err_t	internal_text (const ra8_fmt_sink_t *sink, const char *text)
	Append one NUL-terminated report fragment.
static ra8_err_t	internal_u64 (const ra8_fmt_sink_t *sink, uint64_t value)
	Append one uint64_t as canonical decimal.
static ra8_err_t	internal_hex (const ra8_fmt_sink_t *sink, uint8_t value)
	Append one byte as two uppercase hexadecimal digits.
static void	internal_field (const ra8_fmt_sink_t *sink, uint64_t value, const char *suffix, ra8_err_t *status)
	Append one numeric field and suffix while status succeeds.
static void	internal_geometry (const ra8_fmt_sink_t *report, const jof_info_t *info, const jof_info_t *subject)
	Emit the exact legacy verifier geometry line.
static void	internal_difference (verify_compare_t *state, uint64_t x, uint64_t y, uint8_t reference, uint8_t banded)
	Record and optionally report one differing byte.
static void	internal_abort_dump (verify_compare_t *state)
	Abort an incomplete optional PPM stage once.
static void	internal_dump_bytes (verify_compare_t *state, const uint8_t *bytes, size_t len)
	Append optional PPM bytes or mark the dump failed.
static void	internal_dump_u64 (verify_compare_t *state, uint64_t value)
	Append one decimal PPM header field.
static void	internal_dump_header (verify_compare_t *state)
	Stage the exact P5 or P6 header for subject geometry.
static void	internal_dump_row (verify_compare_t *state, const uint8_t *row)
	Stage one subject row in PPM channel order.
static ra8_err_t	internal_preflight (const ra8_fmt_spool_t *spool, const jof_info_t *info, ra8_fmt_jof_verify_workspace_t *work, bool reference)
	Decode every sealed atlas tile before reporting or output staging.
static void	internal_compare_row (verify_compare_t *state, const uint8_t *band_row, uint16_t y)
	Compare one decoded subject row with its reference row.
static ra8_err_t	internal_compare (verify_compare_t *state)
	Compare all subject bands against streamed reference rows.
static bool	internal_info (const jof_info_t *info, const ra8_fmt_jof_verify_requirements_t *need, uint16_t tile_h)
	Check parsed atlas geometry against exact planned policy.
static void	internal_phase_error (const ra8_fmt_sink_t *report, const char *prefix, ra8_err_t status)
	Report one exact legacy phase-failure line.
static void	internal_finish_dump (verify_compare_t *state, const char *dump_name)
	Commit or abort the optional PPM and emit its legacy status line.
static void	internal_verdict (const ra8_fmt_sink_t *report, uint64_t diffs)
	Emit the exact legacy final verdict line.
static ra8_err_t	internal_check (const ra8_fmt_source_t *reference_source, const ra8_fmt_source_t *banded_source, const ra8_fmt_jof_verify_requirements_t *need, const ra8_fmt_jof_verify_workspace_t *work, const ra8_fmt_spool_t *ref_spool, const ra8_fmt_spool_t *got_spool, const ra8_fmt_sink_t *report)
	Reject incomplete callbacks, aliased contexts, or undersized arenas.
static void	internal_abort_transaction (ra8_fmt_transaction_t *dump)
	Abort an optional complete transaction binding.
static ra8_err_t	internal_accept (const ra8_fmt_spool_t *spool, const ra8_fmt_jof_verify_requirements_t *need, ra8_fmt_jof_verify_workspace_t *work, bool reference, jof_info_t *info)
	Parse, check geometry, and decode every tile of one sealed spool.
static ra8_err_t	internal_prepare (const ra8_fmt_source_t *reference_source, const ra8_fmt_source_t *banded_source, const ra8_fmt_jof_verify_requirements_t *need, ra8_fmt_jof_verify_workspace_t *work, ra8_fmt_spool_t *reference_spool, ra8_fmt_spool_t *banded_spool, const ra8_fmt_sink_t *report, verify_atlases_t *atlases)
	Produce, seal, parse, and preflight both independent atlases.
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 two-spool JOF round-trip verification.

Produces an independently decoded one-row reference atlas and the normal banded subject atlas, validates both, then compares one row at a time. Host paths and descriptors remain behind injected source, spool, transaction, and report callbacks.

Copyright

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

Since

0.1.0

Definition in file ra8_fmt_stream_verify.c.

Enumeration Type Documentation

verify_const_t

enum verify_const_t : uint32_t

Verification geometry, report, and probe constants.

Enumerator
k_verify_band_height	Production band height under test.
k_verify_diffs_max	Maximum detailed byte differences.
k_verify_decimal_max	Digits in one uint64_t.
k_verify_decimal	Decimal report radix.
k_verify_hex_radix	Hexadecimal report radix.
k_verify_ppm_max_text	Bytes in the PPM maximum line.

Definition at line 22 of file ra8_fmt_stream_verify.c.

Function Documentation

internal_abort_dump()

void internal_abort_dump ( verify_compare_t * state )

static

Abort an incomplete optional PPM stage once.

Delegates abort only while the comparison still owns a live stage.

Parameters

[in,out]

state

Comparison state.

Precondition

state is valid.

Optional transaction callbacks are complete.

Postcondition

Any live stage is aborted.

state records that the dump is unavailable.

Note

Idempotent through the dump-ok guard.

Since

0.1.0

Definition at line 391 of file ra8_fmt_stream_verify.c.

References ra8_fmt_transaction_ops_t::abort, ra8_fmt_transaction_t::ctx, verify_compare_t::dump, verify_compare_t::dump_ok, and ra8_fmt_transaction_t::ops.

Referenced by internal_dump_bytes(), internal_finish_dump(), and ra8_fmt_jof_verify_stream().

internal_abort_transaction()

void internal_abort_transaction ( ra8_fmt_transaction_t * dump )

static

Abort an optional complete transaction binding.

Calls abort only when the transaction and callback are present.

Parameters

[in,out]

dump

Optional transaction.

Precondition

dump is null or owns a complete transaction vtable.

No commit is executing concurrently.

Postcondition

Any present stage receives one abort request.

A null or incomplete optional binding causes no dereference.

Note

Used only on pre-comparison failures.

Since

0.1.0

Definition at line 818 of file ra8_fmt_stream_verify.c.

References ra8_fmt_transaction_ops_t::abort, ra8_fmt_transaction_t::ctx, and ra8_fmt_transaction_t::ops.

Referenced by ra8_fmt_jof_verify_stream().

internal_accept()

ra8_err_t internal_accept ( const ra8_fmt_spool_t * spool, const ra8_fmt_jof_verify_requirements_t * need, ra8_fmt_jof_verify_workspace_t * work, bool reference, jof_info_t * info )

static

Parse, check geometry, and decode every tile of one sealed spool.

Replaces producer geometry with independently parsed trusted geometry.

Parameters

[in]	spool	Sealed reference or subject spool.
[in]	need	Exact verifier requirements.
[in,out]	work	Caller decode buffers.
[in]	reference	Select one-row reference geometry.
[in,out]	info	Producer geometry replaced by parsed geometry.

Returns

Parse, geometry, or tile-read status.

Return values

k_ra8_ok	The complete atlas passed every check.
k_ra8_err_validation_failed	Parsed policy differed.
other	Parser or decoder status.

Precondition

Every pointer and callback binding is valid.

spool was sealed at info total size.

Postcondition

Success fully preflights the complete atlas.

No output transaction is staged or published.

Note

Work is bounded by planned geometry and caller buffers.

Since

0.1.0

Definition at line 845 of file ra8_fmt_stream_verify.c.

References ra8_fmt_jof_verify_requirements_t::band_height, ra8_fmt_spool_t::ctx, internal_info(), internal_preflight(), jof_parse(), k_ra8_err_validation_failed, k_ra8_ok, ra8_fmt_spool_t::read_at, and jof_info_t::total_size.

Referenced by internal_prepare().

internal_check()

ra8_err_t internal_check ( const ra8_fmt_source_t * reference_source, const ra8_fmt_source_t * banded_source, const ra8_fmt_jof_verify_requirements_t * need, const ra8_fmt_jof_verify_workspace_t * work, const ra8_fmt_spool_t * ref_spool, const ra8_fmt_spool_t * got_spool, const ra8_fmt_sink_t * report )

static

Reject incomplete callbacks, aliased contexts, or undersized arenas.

Validates every independent binding before producer or transaction mutation.

Parameters

[in]	reference_source	Reference source binding.
[in]	banded_source	Subject source binding.
[in]	need	Exact verifier requirements.
[in]	work	Caller workspace views.
[in]	ref_spool	Reference spool binding.
[in]	got_spool	Subject spool binding.
[in]	report	Report sink.

Returns

Binding validation status.

Return values

k_ra8_ok	Every contract is complete and sufficiently sized.
k_ra8_err_null_ptr	A binding is incomplete or contexts alias.
k_ra8_err_invalid_size	One caller arena is insufficient.

Precondition

Inputs may be null and are checked before dereference.

Requirement capacities are exact planner outputs.

Postcondition

No source, spool, workspace, report, or transaction is mutated.

Success permits safe producer entry.

Note

Pure apart from no state.

Since

0.1.0

Definition at line 767 of file ra8_fmt_stream_verify.c.

References ra8_fmt_spool_t::append, ra8_fmt_jof_verify_requirements_t::band_tile_bytes, ra8_fmt_jof_verify_requirements_t::banded_work_bytes, ra8_fmt_source_t::ctx, ra8_fmt_spool_t::ctx, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_fmt_source_t::read_at, ra8_fmt_spool_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_spool_t::seal, and ra8_fmt_jof_verify_requirements_t::webp_work_bytes.

Referenced by ra8_fmt_jof_verify_stream().

internal_compare()

ra8_err_t internal_compare ( verify_compare_t * state )

static

Compare all subject bands against streamed reference rows.

Decodes one band, compares each row, and stages optional PPM rows.

Parameters

[in,out]

state

Fully prepared comparison state.

Returns

First tile-read or geometry status.

Return values

k_ra8_ok	The complete raster was compared.
k_ra8_err_validation_failed	Decoded geometry was inconsistent.
other	Tile decoder or scratch status.

Precondition

Both spools are sealed, parsed, and preflighted.

All comparison buffers satisfy exact requirements.

Postcondition

Success visits exactly the planned image height.

Optional PPM remains unpublished.

Note

Difference count does not itself stop the full comparison.

Since

0.1.0

Definition at line 592 of file ra8_fmt_stream_verify.c.

References ra8_fmt_spool_t::ctx, verify_compare_t::dump, verify_compare_t::dump_ok, verify_compare_t::ginfo, verify_compare_t::got, ra8_fmt_jof_verify_requirements_t::height, internal_compare_row(), internal_dump_header(), jof_read_tile(), k_ra8_err_validation_failed, k_ra8_ok, verify_compare_t::need, ra8_fmt_spool_t::read_at, verify_compare_t::ref, verify_compare_t::rinfo, ra8_fmt_jof_verify_requirements_t::row_bytes, jof_info_t::tile_rows, and ra8_fmt_jof_verify_requirements_t::width.

Referenced by ra8_fmt_jof_verify_stream().

internal_compare_row()

void internal_compare_row ( verify_compare_t * state, const uint8_t * band_row, uint16_t y )

static

Compare one decoded subject row with its reference row.

Loads the matching reference tile and records differing channel bytes.

Parameters

[in,out]	state	Comparison state.
[in]	band_row	Decoded subject row.
[in]	y	Global raster row.

Precondition

band_row spans the planned row byte count.

y is below planned image height.

Postcondition

Every differing byte in the row increments the count.

At most the legacy detail ceiling is reported globally.

Note

Reference decoding uses the caller-owned row buffer.

Since

0.1.0

Definition at line 561 of file ra8_fmt_stream_verify.c.

References ra8_fmt_jof_verify_requirements_t::bpp, verify_compare_t::diffs, internal_difference(), internal_dump_row(), verify_compare_t::need, and ra8_fmt_jof_verify_requirements_t::row_bytes.

Referenced by internal_compare().

internal_difference()

void internal_difference ( verify_compare_t * state, uint64_t x, uint64_t y, uint8_t reference, uint8_t banded )

static

Record and optionally report one differing byte.

Counts every difference but emits detail only up to the legacy ceiling.

Parameters

[in,out]	state	Comparison state.
[in]	x	Pixel x coordinate.
[in]	y	Pixel y coordinate.
[in]	reference	Reference byte.
[in]	banded	Subject byte.

Precondition

state and its report binding are valid.

Coordinates identify the compared row byte.

Postcondition

Difference count advances exactly once.

At most k_verify_diffs_max detail lines are emitted.

Note

Counter saturation is prevented by bounded raster geometry.

Since

0.1.0

Definition at line 352 of file ra8_fmt_stream_verify.c.

References internal_field(), internal_hex(), internal_text(), k_ra8_ok, k_verify_diffs_max, verify_compare_t::report, and verify_compare_t::shown.

Referenced by internal_compare_row().

internal_dump_bytes()

void internal_dump_bytes ( verify_compare_t * state, const uint8_t * bytes, size_t len )

static

Append optional PPM bytes or mark the dump failed.

Preserves verification progress when a diagnostic output fails.

Parameters

[in,out]	state	Comparison state.
[in]	bytes	PPM bytes.
[in]	len	Exact byte count.

Precondition

state is valid and bytes spans len.

Optional transaction callbacks are complete.

Postcondition

Success extends only the unpublished stage.

Failure aborts the stage and records dump failure.

Note

Dump failure does not alter the comparison verdict.

Since

0.1.0

Definition at line 414 of file ra8_fmt_stream_verify.c.

References ra8_fmt_transaction_ops_t::append, ra8_fmt_transaction_t::ctx, verify_compare_t::dump, verify_compare_t::dump_ok, internal_abort_dump(), k_ra8_ok, and ra8_fmt_transaction_t::ops.

Referenced by internal_dump_header(), internal_dump_row(), and internal_dump_u64().

internal_dump_header()

void internal_dump_header ( verify_compare_t * state )

static

Stage the exact P5 or P6 header for subject geometry.

Selects gray or colour magic and emits dimensions plus sample maximum.

Parameters

[in,out]

state

Comparison state.

Precondition

Subject bpp is one, three, or four.

Optional transaction callbacks are complete.

Postcondition

A live stage contains a complete PPM header.

Unsupported or failed output leaves the stage aborted.

Note

RGBA subjects use P6 and drop alpha in row writes.

Since

0.1.0

Definition at line 462 of file ra8_fmt_stream_verify.c.

References ra8_fmt_jof_verify_requirements_t::bpp, ra8_fmt_jof_verify_requirements_t::height, internal_dump_bytes(), internal_dump_u64(), k_verify_ppm_max_text, verify_compare_t::need, and ra8_fmt_jof_verify_requirements_t::width.

Referenced by internal_compare().

internal_dump_row()

void internal_dump_row ( verify_compare_t * state, const uint8_t * row )

static

Stage one subject row in PPM channel order.

Appends gray/RGB rows directly and strips RGBA alpha per pixel.

Parameters

[in,out]	state	Comparison state.
[in]	row	Decoded subject row.

Precondition

row spans the planned full-width subject bytes.

PPM header staging already ran.

Postcondition

A live stage gains exactly one visible raster row.

Comparison buffers and decoded pixels remain unchanged.

Note

Output remains unpublished until final commit.

Since

0.1.0

Definition at line 485 of file ra8_fmt_stream_verify.c.

References ra8_fmt_jof_verify_requirements_t::bpp, verify_compare_t::dump, verify_compare_t::dump_ok, internal_dump_bytes(), memcpy(), verify_compare_t::need, ra8_fmt_jof_verify_requirements_t::row_bytes, and ra8_fmt_jof_verify_requirements_t::width.

Referenced by internal_compare_row().

internal_dump_u64()

void internal_dump_u64 ( verify_compare_t * state, uint64_t value )

static

Append one decimal PPM header field.

Uses fixed reverse-digit storage through the optional dump helper.

Parameters

[in,out]	state	Comparison state.
[in]	value	Header value.

Precondition

state is valid.

value is a planned image dimension or maximum sample.

Postcondition

A live stage receives the canonical decimal.

A failed stage remains aborted.

Note

No allocation or global storage is used.

Since

0.1.0

Definition at line 435 of file ra8_fmt_stream_verify.c.

References internal_dump_bytes(), k_verify_decimal, and k_verify_decimal_max.

Referenced by internal_dump_header().

internal_field()

void internal_field ( const ra8_fmt_sink_t * sink, uint64_t value, const char * suffix, ra8_err_t * status )

static

Append one numeric field and suffix while status succeeds.

Preserves the first report-sink error across chained appends.

Parameters

[in]	sink	Bound report sink.
[in]	value	Numeric field.
[in]	suffix	NUL-terminated suffix.
[in,out]	status	Current and resulting report status.

Precondition

Every pointer argument is non-null.

status contains the prior append result.

Postcondition

Existing failure skips every append.

Success appends both field and suffix.

Note

Thread safety inherits the sink.

Since

0.1.0

Definition at line 301 of file ra8_fmt_stream_verify.c.

References internal_text(), internal_u64(), and k_ra8_ok.

Referenced by internal_difference(), internal_geometry(), internal_phase_error(), and internal_verdict().

internal_finish_dump()

void internal_finish_dump ( verify_compare_t * state, const char * dump_name )

static

Commit or abort the optional PPM and emit its legacy status line.

Publishes only a complete stage after comparison and stability checks.

Parameters

[in,out]	state	Comparison state.
[in]	dump_name	Output spelling.

Precondition

state is valid.

A non-null dump has a non-null dump_name.

Postcondition

A complete stage is committed; any failed stage is aborted.

Exactly one best-effort output status line is emitted.

Note

Output failure does not alter the exact comparison verdict.

Since

0.1.0

Definition at line 701 of file ra8_fmt_stream_verify.c.

References ra8_fmt_transaction_ops_t::commit, ra8_fmt_transaction_t::ctx, verify_compare_t::dump, verify_compare_t::dump_ok, internal_abort_dump(), internal_text(), k_ra8_ok, ra8_fmt_transaction_t::ops, and verify_compare_t::report.

Referenced by ra8_fmt_jof_verify_stream().

internal_geometry()

void internal_geometry ( const ra8_fmt_sink_t * report, const jof_info_t * info, const jof_info_t * subject )

static

Emit the exact legacy verifier geometry line.

Reports trusted reference and subject dimensions and tiling.

Parameters

[in]	report	Bound report sink.
[in]	info	Trusted reference geometry.
[in]	subject	Trusted banded geometry.

Precondition

Every pointer argument is valid.

Both geometries passed full parse and decode preflight.

Postcondition

Best effort emits one newline-terminated geometry line.

Geometry inputs remain unchanged.

Note

Report failures do not mutate verification state.

Since

0.1.0

Definition at line 326 of file ra8_fmt_stream_verify.c.

References jof_info_t::bpp, jof_info_t::height, internal_field(), internal_text(), jof_info_t::tile_count, jof_info_t::tile_h, and jof_info_t::width.

Referenced by ra8_fmt_jof_verify_stream().

internal_hex()

ra8_err_t internal_hex ( const ra8_fmt_sink_t * sink, uint8_t value )

static

Append one byte as two uppercase hexadecimal digits.

Emits the high then low nibble through one exact sink call.

Parameters

[in]	sink	Bound report sink.
[in]	value	Byte value.

Returns

Sink status.

Return values

k_ra8_ok	Both digits were appended.
other	Injected sink failure.

Precondition

sink and callback are valid.

value is one complete byte.

Postcondition

Success appends exactly two uppercase digits.

No caller input changes.

Note

Pure apart from the injected sink.

Since

0.1.0

Definition at line 275 of file ra8_fmt_stream_verify.c.

References ra8_fmt_sink_t::ctx, k_verify_hex_radix, and ra8_fmt_sink_t::write.

Referenced by internal_difference().

internal_info()

bool internal_info ( const jof_info_t * info, const ra8_fmt_jof_verify_requirements_t * need, uint16_t tile_h )

static

Check parsed atlas geometry against exact planned policy.

Requires one full-width column and the requested row/band tiling.

Parameters

[in]	info	Parsed atlas geometry.
[in]	need	Exact verifier requirements.
[in]	tile_h	Expected tile height.

Returns

Whether every geometry and codec invariant matches.

Return values

true	The atlas matches the complete policy.
false	One geometry, tile-count, bpp, or codec field differs.

Precondition

info and need are non-null.

Both structures are completely initialized.

Postcondition

Neither structure changes.

Classification is deterministic.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 657 of file ra8_fmt_stream_verify.c.

References jof_info_t::bpp, ra8_fmt_jof_verify_requirements_t::bpp, jof_info_t::codec, jof_info_t::height, ra8_fmt_jof_verify_requirements_t::height, k_jof_codec_deflate, jof_info_t::tile_cols, jof_info_t::tile_count, jof_info_t::tile_h, jof_info_t::tile_rows, jof_info_t::tile_w, jof_info_t::width, and ra8_fmt_jof_verify_requirements_t::width.

Referenced by internal_accept().

internal_phase_error()

void internal_phase_error ( const ra8_fmt_sink_t * report, const char * prefix, ra8_err_t status )

static

Report one exact legacy phase-failure line.

Appends a fixed prefix, decimal status, and closing line syntax.

Parameters

[in]	report	Bound report sink.
[in]	prefix	NUL-terminated phase prefix.
[in]	status	Phase failure status.

Precondition

report and prefix are valid.

The prefix leaves the status parenthesis open.

Postcondition

Best effort emits one newline-terminated line.

No verification state changes.

Note

Sink failure is not recursively reported.

Since

0.1.0

Definition at line 682 of file ra8_fmt_stream_verify.c.

References internal_field(), and internal_text().

Referenced by internal_prepare().

internal_preflight()

ra8_err_t internal_preflight ( const ra8_fmt_spool_t * spool, const jof_info_t * info, ra8_fmt_jof_verify_workspace_t * work, bool reference )

static

Decode every sealed atlas tile before reporting or output staging.

Validates dimensions for each reference row or subject band.

Parameters

[in]	spool	Sealed atlas binding.
[in]	info	Trusted parsed geometry.
[in,out]	work	Caller decode buffers.
[in]	reference	Select reference-row buffer use.

Returns

First tile-read or geometry status.

Return values

k_ra8_ok	Every tile decoded with exact dimensions.
k_ra8_err_validation_failed	A decoded tile shape differed.
other	Parser, decompressor, or scratch status.

Precondition

Every pointer and callback binding is valid.

info total size matches the sealed spool.

Postcondition

Success proves every tile can be fully decoded.

No output transaction is opened or published.

Note

Work is bounded by trusted tile counts and caller buffers.

Since

0.1.0

Definition at line 519 of file ra8_fmt_stream_verify.c.

References ra8_fmt_spool_t::ctx, jof_read_tile(), k_ra8_err_validation_failed, k_ra8_ok, ra8_fmt_spool_t::read_at, jof_info_t::tile_rows, and jof_info_t::width.

Referenced by internal_accept().

internal_prepare()

ra8_err_t internal_prepare ( const ra8_fmt_source_t * reference_source, const ra8_fmt_source_t * banded_source, const ra8_fmt_jof_verify_requirements_t * need, ra8_fmt_jof_verify_workspace_t * work, ra8_fmt_spool_t * reference_spool, ra8_fmt_spool_t * banded_spool, const ra8_fmt_sink_t * report, verify_atlases_t * atlases )

static

Produce, seal, parse, and preflight both independent atlases.

Completes the row-reference phase before starting the banded subject.

Parameters

[in]	reference_source	First encoded-source context.
[in]	banded_source	Second encoded-source context.
[in]	need	Exact verifier requirements.
[in,out]	work	Phase-reused caller workspace.
[in,out]	reference_spool	Empty reference spool.
[in,out]	banded_spool	Empty subject spool.
[in]	report	Legacy report sink.
[out]	atlases	Receives trusted parsed geometry.

Returns

First producer, spool, parse, or decode status.

Return values

k_ra8_ok	Both atlases are sealed and trusted.
other	First reference or subject phase failure.

Precondition

All bindings are independent and validated.

Workspace satisfies the exact planner requirements.

Postcondition

Success leaves both spools sealed and fully decoded once.

Failure emits exactly one legacy phase diagnostic.

Note

No output transaction is published in preparation.

Since

0.1.0

Definition at line 884 of file ra8_fmt_stream_verify.c.

References ra8_fmt_jof_verify_requirements_t::band_height, verify_atlases_t::banded, internal_accept(), internal_phase_error(), internal_produce(), k_ra8_ok, and verify_atlases_t::reference.

Referenced by ra8_fmt_jof_verify_stream().

internal_produce()

ra8_err_t internal_produce ( const ra8_fmt_source_t * source, const ra8_fmt_jof_verify_requirements_t * need, uint16_t tile_h, ra8_fmt_jof_verify_workspace_t * work, ra8_fmt_spool_t * spool, jof_info_t * info )

static

Produce and seal one deflate JOF into an injected spool.

Binds a sequential pull cursor and exact caller arenas to the producer.

Parameters

[in]	source	Encoded immutable source.
[in]	need	Exact verifier requirements.
[in]	tile_h	Requested reference-row or subject-band height.
[in,out]	work	Caller-owned producer arenas.
[in,out]	spool	Empty append/seal scratch binding.
[out]	info	Receives produced geometry and extent.

Returns

Producer, stability, or seal status.

Return values

k_ra8_ok	The complete atlas is stable and sealed.
other	Source, producer, mutation, or spool status.

Precondition

Every pointer and callback binding is valid.

Workspace capacities satisfy need.

Postcondition

Success leaves spool sealed at info total size.

Failure publishes no output transaction.

Note

Producer execution is bounded by source geometry and caller storage.

Since

0.1.0

Definition at line 171 of file ra8_fmt_stream_verify.c.

References ra8_fmt_spool_t::ctx, ra8_fmt_jof_verify_requirements_t::height, internal_pull(), internal_spool_append(), internal_stable(), jof_produce(), k_jof_codec_deflate, k_ra8_ok, ra8_fmt_spool_t::seal, jof_info_t::total_size, and ra8_fmt_jof_verify_requirements_t::width.

Referenced by internal_prepare().

internal_pull()

ra8_err_t internal_pull ( void * ctx, uint8_t * bytes, size_t cap, size_t * got )

static

Pull the next bounded source prefix for streamed JOF production.

Reads at the cursor's current offset, validates the backend's reported count, and advances only after a successful bounded read.

Parameters

[in,out]	ctx	Mutable verify_pull_t cursor context.
[out]	bytes	Destination for the next source prefix.
[in]	cap	Writable capacity of bytes.
[out]	got	Number of bytes returned by the source.

Returns

Canonical stream callback status.

Return values

k_ra8_ok	A valid prefix or clean end-of-source was returned.
k_ra8_err_null_ptr	A required callback argument was null.
k_ra8_err_protocol_error	The source reported more than cap.
other	Propagated source read error.

Precondition

Nonzero cap requires writable bytes storage.

The cursor source and got remain valid for the call.

Postcondition

Success advances the cursor by exactly *got bytes.

Failure never advances past an unvalidated source result.

Note

The callback performs no allocation and never retains bytes.

Since

0.1.0

Definition at line 104 of file ra8_fmt_stream_verify.c.

References ra8_fmt_source_t::ctx, k_ra8_err_null_ptr, k_ra8_err_protocol_error, k_ra8_ok, verify_pull_t::offset, ra8_fmt_source_t::read_at, ra8_fmt_source_t::size, and verify_pull_t::source.

internal_spool_append()

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

static

Append one produced JOF span to the injected verifier spool.

Adapts the producer sink signature directly to the caller-owned spool without retaining the supplied byte span.

Parameters

[in,out]	ctx	Caller-owned ra8_fmt_spool_t descriptor.
[in]	bytes	Produced JOF bytes to append.
[in]	len	Number of bytes in bytes.

Returns

Canonical spool append status.

Return values

k_ra8_ok	The complete span was accepted.
other	Propagated spool append failure.

Precondition

ctx points to a bound spool with a valid append callback.

Nonzero len requires a readable bytes span.

Postcondition

The callback result exactly matches the injected append result.

This adapter retains no caller-owned pointer.

Note

Capacity and publication policy belong to the injected spool.

Since

0.1.0

Definition at line 145 of file ra8_fmt_stream_verify.c.

References ra8_fmt_spool_t::append, and ra8_fmt_spool_t::ctx.

Referenced by internal_produce().

internal_stable()

ra8_err_t internal_stable ( const ra8_fmt_source_t * source )

static

Validate a source through its optional stability callback.

Delegates immutable-view revalidation while preserving optional bindings.

Parameters

[in]

source

Source to validate.

Returns

Stability callback status or success when validation is absent.

Return values

k_ra8_ok	The source is unchanged or has no validator.
other	The backend observed mutation or validation failure.

Precondition

source is non-null.

The captured size still describes the intended object.

Postcondition

No source position changes.

Success permits continued trust in the captured view.

Note

Thread safety inherits the backend validator.

Since

0.1.0

Definition at line 78 of file ra8_fmt_stream_verify.c.

References ra8_fmt_source_t::ctx, k_ra8_ok, ra8_fmt_source_t::size, and ra8_fmt_source_t::validate.

Referenced by internal_produce(), and ra8_fmt_jof_verify_stream().

internal_text()

ra8_err_t internal_text ( const ra8_fmt_sink_t * sink, const char * text )

static

Append one NUL-terminated report fragment.

Measures the fixed spelling and delegates one exact sink write.

Parameters

[in]	sink	Bound report sink.
[in]	text	NUL-terminated spelling.

Returns

Sink status.

Return values

k_ra8_ok	The complete spelling was appended.
other	Injected sink failure.

Precondition

sink and callback are valid.

text is NUL-terminated.

Postcondition

Success appends exactly strlen(text) bytes.

No input byte changes.

Note

Thread safety inherits the sink.

Since

0.1.0

Definition at line 223 of file ra8_fmt_stream_verify.c.

References ra8_fmt_sink_t::ctx, strlen(), and ra8_fmt_sink_t::write.

Referenced by internal_difference(), internal_field(), internal_finish_dump(), internal_geometry(), internal_phase_error(), and internal_verdict().

internal_u64()

ra8_err_t internal_u64 ( const ra8_fmt_sink_t * sink, uint64_t value )

static

Append one uint64_t as canonical decimal.

Uses fixed reverse-digit storage and emits no terminator.

Parameters

[in]	sink	Bound report sink.
[in]	value	Value to spell.

Returns

Sink status.

Return values

k_ra8_ok	The complete decimal was appended.
other	Injected sink failure.

Precondition

sink and callback are valid.

Fixed storage spans k_verify_decimal_max digits.

Postcondition

Success appends only decimal digits.

No global state changes.

Note

Thread safety inherits the sink.

Since

0.1.0

Definition at line 244 of file ra8_fmt_stream_verify.c.

References ra8_fmt_sink_t::ctx, k_verify_decimal, k_verify_decimal_max, and ra8_fmt_sink_t::write.

Referenced by internal_field().

internal_verdict()

void internal_verdict ( const ra8_fmt_sink_t * report, uint64_t diffs )

static

Emit the exact legacy final verdict line.

Selects exact or mismatch wording from the complete difference count.

Parameters

[in]	report	Bound report sink.
[in]	diffs	Complete differing-byte count.

Precondition

report and its callback are valid.

Full comparison and final stability checks completed.

Postcondition

Best effort emits one newline-terminated verdict.

No comparison or output state changes.

Note

Sink failure does not change the returned verifier status.

Since

0.1.0

Definition at line 731 of file ra8_fmt_stream_verify.c.

References internal_field(), internal_text(), and k_ra8_ok.

Referenced by ra8_fmt_jof_verify_stream().

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().