ra8_fmt_portable_verify.c File Reference

Raw-fd composition root for bounded two-spool JOF verification. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <unistd.h>
#include "ra8_attributes.h"
#include "ra8_fmt_host_fd_internal.h"
#include "ra8_fmt_host_spool_internal.h"
#include "ra8_fmt_portable_main_internal.h"
#include "ra8_fmt_stream.h"

Include dependency graph for ra8_fmt_portable_verify.c:

Go to the source code of this file.

Data Structures
struct	verify_cli_args_t
	Parsed legacy-compatible JOF verify selections. More...
struct	verify_layout_t
	Exact phase-overlaid byte offsets in the shared composition arena. More...

Enumerations
enum	verify_cli_const_t : uint32_t {   k_verify_cli_ok = 0U ,   k_verify_cli_fail = 1U ,   k_verify_cli_input = 268435456U ,   k_verify_cli_align = 16U ,   k_verify_cli_digits = 20U ,   k_verify_cli_decimal = 10U }
	CLI and workspace-layout constants. More...

Functions
static ra8_err_t	internal_text (const ra8_fmt_sink_t *sink, const char *text)
	Append one NUL-terminated text fragment.
static ra8_err_t	internal_u64 (const ra8_fmt_sink_t *sink, uint64_t value)
	Append one uint64_t in decimal.
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_status (const ra8_fmt_sink_t *sink, const char *prefix, ra8_err_t status)
	Emit one canonical status diagnostic.
static bool	internal_parse (int argc, char **argv, verify_cli_args_t *args)
	Parse only the legacy JOF verify option spellings.
static bool	internal_align (size_t value, size_t *out)
	Align one size to the composition slice boundary.
static bool	internal_add (size_t offset, size_t bytes, size_t *next)
	Add one aligned arena slice without size_t wrapping.
static bool	internal_layout (const ra8_fmt_jof_verify_requirements_t *need, verify_layout_t *layout)
	Compute exact maximum high-water across producer and compare phases.
static void	internal_capacity (const ra8_fmt_sink_t *errors, const ra8_fmt_jof_verify_requirements_t *need, const verify_layout_t *layout, size_t supplied)
	Report exact required and supplied shared-workspace evidence.
static ra8_err_t	internal_failed_append (void *ctx, const uint8_t *bytes, size_t len)
	Append text or binary bytes to a bounded backend.
static ra8_err_t	internal_failed_commit (void *ctx)
	Report commit failure for an unavailable optional output.
static void	internal_failed_abort (void *ctx)
	Abort an output transaction that never began.
static void	internal_bind (ra8_fmt_cli_workspace_t *root, const ra8_fmt_jof_verify_requirements_t *need, const verify_layout_t *layout, ra8_fmt_jof_verify_workspace_t *out)
	Bind phase-overlaid producer and comparison arena views.
static void	internal_cleanup (ra8_fmt_host_source_t *ref, ra8_fmt_host_source_t *got, ra8_fmt_host_spool_t *ref_spool, ra8_fmt_host_spool_t *got_spool)
	Close all verifier-owned source and spool descriptors.
static ra8_err_t	internal_run (const ra8_fmt_host_source_t *ref, const ra8_fmt_host_source_t *got, const ra8_fmt_jof_verify_requirements_t *need, ra8_fmt_jof_verify_workspace_t *work, ra8_fmt_spool_t *ref_spool, ra8_fmt_spool_t *got_spool, ra8_fmt_transaction_t *dump, const char *dump_name, const ra8_fmt_sink_t *report)
	Run the fully bound portable verifier engine.
static int	internal_execute (const verify_cli_args_t *args, ra8_fmt_cli_workspace_t *workspace, ra8_fmt_host_source_t *ref_source, ra8_fmt_host_source_t *got_source, const ra8_fmt_jof_verify_requirements_t *need, const verify_layout_t *layout, const ra8_fmt_sink_t *errors, const ra8_fmt_sink_t *report)
	Bind host spools and optional output, run, and close every owner.
static ra8_err_t	internal_open_and_size (const verify_cli_args_t *args, size_t workspace_bytes, ra8_fmt_host_source_t *ref_source, ra8_fmt_host_source_t *got_source, ra8_fmt_jof_verify_requirements_t *need, verify_layout_t *layout, const ra8_fmt_sink_t *errors, const ra8_fmt_sink_t *report)
	Open both verify sources and compute the workspace sizing.
int	priv_fmt_try_portable_verify (int argc, char **argv, ra8_fmt_cli_workspace_t *workspace, bool *handled)
	Try the bounded two-spool JOF-verification command path.

Variables
static const ra8_fmt_transaction_ops_t	s_failed_transaction_ops

Detailed Description

Raw-fd composition root for bounded two-spool JOF verification.

Opens two immutable source contexts, plans exact phase-overlaid workspace, creates anonymous sibling spools, and optionally binds a durable PPM transaction. All owned descriptors are closed on every path.

Copyright

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

Since

0.1.0

Definition in file ra8_fmt_portable_verify.c.

Enumeration Type Documentation

verify_cli_const_t

enum verify_cli_const_t : uint32_t

CLI and workspace-layout constants.

Enumerator
k_verify_cli_ok	Successful exact verdict.
k_verify_cli_fail	Verification or host failure.
k_verify_cli_input	Maximum encoded input (256 MiB).
k_verify_cli_align	Arena slice alignment.
k_verify_cli_digits	Digits in uint64_t.
k_verify_cli_decimal	Decimal formatting radix.

Definition at line 24 of file ra8_fmt_portable_verify.c.

Function Documentation

internal_add()

bool internal_add ( size_t offset, size_t bytes, size_t * next )

static

Add one aligned arena slice without size_t wrapping.

Aligns the incoming offset before checked slice addition.

Parameters

[in]	offset	Current phase offset.
[in]	bytes	Slice bytes.
[out]	next	Receives the next unaligned phase offset.

Returns

Whether alignment and addition were representable.

Return values

true	next contains the exact slice end.
false	Alignment or addition overflowed.

Precondition

next is writable.

offset describes the current phase arena.

Postcondition

Success initializes next.

Failure performs no allocation or I/O.

Note

Pure apart from caller output.

Since

0.1.0

Definition at line 227 of file ra8_fmt_portable_verify.c.

References internal_align().

internal_align()

bool internal_align ( size_t value, size_t * out )

static

Align one size to the composition slice boundary.

Checks addition before rounding up to k_verify_cli_align.

Parameters

[in]	value	Unaligned byte count.
[out]	out	Receives the aligned count.

Returns

Whether alignment is representable.

Return values

true	out contains the aligned count.
false	Rounding would overflow size_t.

Precondition

out is writable.

k_verify_cli_align is a power of two.

Postcondition

Success initializes out.

Failure performs no allocation or I/O.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 200 of file ra8_fmt_portable_verify.c.

References k_verify_cli_align.

Referenced by internal_add(), and internal_layout().

internal_bind()

void internal_bind ( ra8_fmt_cli_workspace_t * root, const ra8_fmt_jof_verify_requirements_t * need, const verify_layout_t * layout, ra8_fmt_jof_verify_workspace_t * out )

static

Bind phase-overlaid producer and comparison arena views.

Maps validated exact offsets into the caller-owned composition root.

Parameters

[in,out]	root	Shared composition workspace.
[in]	need	Exact verifier requirements.
[in]	layout	Validated exact offsets.
[out]	out	Receives every engine arena view.

Precondition

Every pointer argument is non-null.

layout total fits root storage.

Postcondition

All spans lie within layout total bytes.

No workspace byte is initialized or allocated.

Note

Spans overlap only across non-concurrent phases.

Since

0.1.0

Definition at line 374 of file ra8_fmt_portable_verify.c.

References ra8_fmt_jof_verify_requirements_t::band_tile_bytes, ra8_fmt_cli_workspace_t::bytes, nullptr, verify_layout_t::producer, verify_layout_t::row, ra8_fmt_jof_verify_requirements_t::row_bytes, verify_layout_t::scratch, ra8_fmt_jof_verify_requirements_t::scratch_bytes, verify_layout_t::webp, and ra8_fmt_jof_verify_requirements_t::webp_work_bytes.

Referenced by internal_execute().

internal_capacity()

void internal_capacity ( const ra8_fmt_sink_t * errors, const ra8_fmt_jof_verify_requirements_t * need, const verify_layout_t * layout, size_t supplied )

static

Report exact required and supplied shared-workspace evidence.

Emits the high-water plus every contributing phase component.

Parameters

[in]	errors	Standard-error sink.
[in]	need	Exact verifier requirements.
[in]	layout	Computed exact offsets.
[in]	supplied	Caller workspace capacity.

Precondition

Every pointer argument is valid.

layout corresponds to need.

Postcondition

Best effort emits one bounded diagnostic line.

Workspace and requirements remain unchanged.

Note

Sink failures are intentionally ignored after first failure.

Since

0.1.0

Definition at line 291 of file ra8_fmt_portable_verify.c.

References ra8_fmt_jof_verify_requirements_t::band_tile_bytes, internal_field(), internal_text(), verify_layout_t::producer, ra8_fmt_jof_verify_requirements_t::row_bytes, ra8_fmt_jof_verify_requirements_t::scratch_bytes, verify_layout_t::total, and ra8_fmt_jof_verify_requirements_t::webp_work_bytes.

Referenced by internal_open_and_size().

internal_cleanup()

void internal_cleanup ( ra8_fmt_host_source_t * ref, ra8_fmt_host_source_t * got, ra8_fmt_host_spool_t * ref_spool, ra8_fmt_host_spool_t * got_spool )

static

Close all verifier-owned source and spool descriptors.

Performs idempotent cleanup in scratch-then-source order.

Parameters

[in,out]	ref	Reference source state.
[in,out]	got	Subject source state.
[in,out]	ref_spool	Reference scratch state, optionally null.
[in,out]	got_spool	Subject scratch state, optionally null.

Precondition

Non-null states were initialized closed or successfully opened.

No callback is executing through the states.

Postcondition

Every owned descriptor is closed.

Repeated cleanup leaves all states closed.

Note

Sequential composition-root cleanup only.

Since

0.1.0

Definition at line 408 of file ra8_fmt_portable_verify.c.

References priv_fmt_host_source_close(), and priv_fmt_host_spool_close().

Referenced by internal_execute(), and internal_open_and_size().

internal_execute()

int internal_execute ( const verify_cli_args_t * args, ra8_fmt_cli_workspace_t * workspace, ra8_fmt_host_source_t * ref_source, ra8_fmt_host_source_t * got_source, const ra8_fmt_jof_verify_requirements_t * need, const verify_layout_t * layout, const ra8_fmt_sink_t * errors, const ra8_fmt_sink_t * report )

static

Bind host spools and optional output, run, and close every owner.

Creates anonymous sibling spools and a durable optional transaction.

Parameters

[in]	args	Valid portable verify arguments.
[in,out]	workspace	Shared composition arena.
[in,out]	ref_source	Open reference source, always closed here.
[in,out]	got_source	Open subject source, always closed here.
[in]	need	Exact verifier requirements.
[in]	layout	Validated arena layout.
[in]	errors	Standard-error sink.
[in]	report	Standard-output sink.

Returns

Portable CLI status.

Return values

0	Verification completed exactly.
1	Spool, output, producer, decoder, or comparison failed.

Precondition

Every required pointer and sink binding is valid.

Both source owners are open independent descriptors.

Postcondition

Every source, spool, and still-active transaction is closed.

Output is published only after complete comparison and stability checks.

Note

Single-threaded composition root; engine contexts remain injectable.

Since

0.1.0

Definition at line 485 of file ra8_fmt_portable_verify.c.

References ra8_fmt_transaction_ops_t::abort, ra8_fmt_host_transaction_t::active, ra8_fmt_transaction_t::ctx, verify_cli_args_t::input, internal_bind(), internal_cleanup(), internal_run(), internal_status(), k_ra8_ok, k_verify_cli_fail, k_verify_cli_ok, ra8_fmt_transaction_t::ops, verify_cli_args_t::output, priv_fmt_host_spool_open(), priv_fmt_host_transaction_begin(), and s_failed_transaction_ops.

Referenced by priv_fmt_try_portable_verify().

internal_failed_abort()

void internal_failed_abort ( void * ctx )

static

Abort an output transaction that never began.

Supplies a complete transaction vtable after secure open failure.

Parameters

[in]

ctx

Unused null context.

Precondition

ctx is null.

No stage descriptor is owned.

Postcondition

No filesystem object is created or changed.

Repeated calls remain harmless.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 348 of file ra8_fmt_portable_verify.c.

internal_failed_append()

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

static

Append text or binary bytes to a bounded backend.

Definition at line 308 of file ra8_fmt_portable_verify.c.

References k_ra8_fail.

internal_failed_commit()

ra8_err_t internal_failed_commit ( void * ctx )

static

Report commit failure for an unavailable optional output.

Models an output transaction that could not be opened securely.

Parameters

[in]

ctx

Unused null context.

Returns

Constant failure status.

Return values

k_ra8_fail

No output transaction exists.

Precondition

ctx is null.

No stage descriptor is owned.

Postcondition

No filesystem object is created or changed.

The modeled transaction remains failed.

Note

Pure and thread-safe.

Since

0.1.0

Definition at line 330 of file ra8_fmt_portable_verify.c.

References k_ra8_fail.

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 sink error across the chained report operation.

Parameters

[in]	sink	Bound output 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 117 of file ra8_fmt_portable_verify.c.

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

Referenced by internal_capacity(), and internal_status().

internal_layout()

bool internal_layout ( const ra8_fmt_jof_verify_requirements_t * need, verify_layout_t * layout )

static

Compute exact maximum high-water across producer and compare phases.

Overlays mutually exclusive phases while aligning every simultaneous slice.

Parameters

[in]	need	Exact engine requirements.
[out]	layout	Receives offsets and maximum phase high-water.

Returns

Whether every offset is representable.

Return values

true	Every exact slice and high-water fits size_t.
false	One alignment or addition overflowed.

Precondition

need and layout are non-null.

Requirement fields came from the bounded planner.

Postcondition

Success initializes all layout fields.

Failure performs no workspace write.

Note

Producer and comparison phases intentionally overlap byte zero.

Since

0.1.0

Definition at line 253 of file ra8_fmt_portable_verify.c.

References ra8_fmt_jof_verify_requirements_t::band_tile_bytes, ra8_fmt_jof_verify_requirements_t::banded_work_bytes, internal_add(), internal_align(), internal_align(), verify_layout_t::producer, ra8_fmt_jof_verify_requirements_t::reference_work_bytes, verify_layout_t::row, ra8_fmt_jof_verify_requirements_t::row_bytes, verify_layout_t::scratch, ra8_fmt_jof_verify_requirements_t::scratch_bytes, verify_layout_t::total, verify_layout_t::webp, and ra8_fmt_jof_verify_requirements_t::webp_work_bytes.

Referenced by internal_open_and_size().

internal_open_and_size()

ra8_err_t internal_open_and_size ( const verify_cli_args_t * args, size_t workspace_bytes, ra8_fmt_host_source_t * ref_source, ra8_fmt_host_source_t * got_source, ra8_fmt_jof_verify_requirements_t * need, verify_layout_t * layout, const ra8_fmt_sink_t * errors, const ra8_fmt_sink_t * report )

static

Open both verify sources and compute the workspace sizing.

Opens the reference and comparison file descriptors on the same input, confirms they observe the identical unchanged file, then derives the JOF verify requirements and workspace layout.

Parameters

[in]	args	Parsed CLI arguments (input path).
[in]	workspace_bytes	Capacity of the CLI workspace scratch, in bytes.
[out]	ref_source	Opened reference-pass source.
[out]	got_source	Opened comparison-pass source.
[out]	need	Derived JOF verify requirements.
[out]	layout	Derived workspace layout.
[in]	errors	Sink for open/validation diagnostics.
[in]	report	Sink for capacity diagnostics.

Returns

Open/sizing status.

Return values

k_ra8_ok	Both sources are open, identical, unchanged, and sized.
other	Open, identity, sizing, or capacity validation failed (already reported and cleaned up).

Precondition

args->input names a readable file.

Every output pointer and both sink bindings are valid and independent.

Postcondition

On failure both sources are closed and no partial state escapes.

On success both open sources pass to the caller, which must close them.

Note

Not thread-safe with respect to concurrent mutation of the input.

Since

0.1.0

Definition at line 559 of file ra8_fmt_portable_verify.c.

References verify_cli_args_t::input, internal_capacity(), internal_cleanup(), internal_layout(), internal_status(), k_ra8_err_invalid_size, k_ra8_err_validation_failed, k_ra8_ok, k_verify_cli_input, priv_fmt_host_source_open(), priv_fmt_host_source_unchanged(), priv_fmt_host_sources_same(), ra8_fmt_jof_verify_requirements(), RA8_INTERNAL, ra8_fmt_host_source_t::source, and verify_layout_t::total.

Referenced by priv_fmt_try_portable_verify().

internal_parse()

bool internal_parse ( int argc, char ** argv, verify_cli_args_t * args )

static

Parse only the legacy JOF verify option spellings.

Accepts explicit format, input, output, verbosity, and one positional input.

Parameters

[in]	argc	Argument count.
[in]	argv	Argument vector.
[out]	args	Receives paths and format.

Returns

Whether every option was recognized and complete.

Return values

true	Every token was accepted.
false	An unknown or incomplete option was found.

Precondition

argv spans argc pointers.

args is zero-initialized and writable.

Postcondition

Success retains only pointers into argv.

Failure performs no I/O or ownership transfer.

Note

Parsing is deterministic and performs no I/O.

Since

0.1.0

Definition at line 164 of file ra8_fmt_portable_verify.c.

References verify_cli_args_t::format, verify_cli_args_t::input, verify_cli_args_t::output, and strcmp().

Referenced by priv_fmt_try_portable_verify().

internal_run()

ra8_err_t internal_run ( const ra8_fmt_host_source_t * ref, const ra8_fmt_host_source_t * got, const ra8_fmt_jof_verify_requirements_t * need, ra8_fmt_jof_verify_workspace_t * work, ra8_fmt_spool_t * ref_spool, ra8_fmt_spool_t * got_spool, ra8_fmt_transaction_t * dump, const char * dump_name, const ra8_fmt_sink_t * report )

static

Run the fully bound portable verifier engine.

Adapts host-source owners to portable source views without new ownership.

Parameters

[in]	ref	First source context.
[in]	got	Second source context.
[in]	need	Exact requirements.
[in,out]	work	Phase-overlaid arena views.
[in,out]	ref_spool	Reference scratch binding.
[in,out]	got_spool	Subject scratch binding.
[in,out]	dump	Optional PPM transaction.
[in]	dump_name	Optional PPM spelling.
[in]	report	Standard-output report sink.

Returns

Engine status.

Return values

k_ra8_ok	The complete comparison was exact.
other	Producer, decoder, stability, or comparison status.

Precondition

All required source, spool, workspace, and report bindings are valid.

Optional dump and name are either both present or both absent.

Postcondition

Engine-owned transaction state is committed or aborted.

Host descriptor ownership remains with the caller.

Note

Thread safety inherits independent bound contexts.

Since

0.1.0

Definition at line 442 of file ra8_fmt_portable_verify.c.

References ra8_fmt_jof_verify_stream(), and ra8_fmt_host_source_t::source.

Referenced by internal_execute().

internal_status()

void internal_status ( const ra8_fmt_sink_t * sink, const char * prefix, ra8_err_t status )

static

Emit one canonical status diagnostic.

Appends a fixed prefix, decimal status, close parenthesis, and newline.

Parameters

[in]	sink	Bound diagnostic sink.
[in]	prefix	NUL-terminated diagnostic prefix.
[in]	status	Status value to report.

Precondition

sink and prefix are valid.

The prefix leaves the numeric parenthesis open.

Postcondition

Best effort emits one complete diagnostic line.

No caller input changes.

Note

Sink failures are intentionally not recursive.

Since

0.1.0

Definition at line 141 of file ra8_fmt_portable_verify.c.

References internal_field(), and internal_text().

Referenced by internal_execute(), and internal_open_and_size().

internal_text()

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

static

Append one NUL-terminated text fragment.

Measures the fixed spelling and delegates one exact sink write.

Parameters

[in]	sink	Bound output 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 its 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 65 of file ra8_fmt_portable_verify.c.

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

Referenced by internal_capacity(), internal_field(), and internal_status().

internal_u64()

ra8_err_t internal_u64 ( const ra8_fmt_sink_t * sink, uint64_t value )

static

Append one uint64_t in decimal.

Uses fixed reverse-digit storage and emits no terminator.

Parameters

[in]	sink	Bound output 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 its callback are valid.

Fixed digit storage spans k_verify_cli_digits bytes.

Postcondition

Success appends the canonical unsigned decimal.

No global or input state changes.

Note

Thread safety inherits the sink.

Since

0.1.0

Definition at line 86 of file ra8_fmt_portable_verify.c.

References ra8_fmt_sink_t::ctx, k_verify_cli_decimal, k_verify_cli_digits, and ra8_fmt_sink_t::write.

Referenced by internal_field().

priv_fmt_try_portable_verify()

int priv_fmt_try_portable_verify ( int argc, char ** argv, ra8_fmt_cli_workspace_t * workspace, bool * handled )

nodiscard

Try the bounded two-spool JOF-verification command path.

Parameters

[in]	argc	Process argument count.
[in]	argv	Process argument vector.
[in,out]	workspace	Explicit shared composition-root arena.
[out]	handled	Set when this function owns the exit status.

Returns

Process exit status when handled; unspecified otherwise.

Precondition

workspace is aligned for every producer and decode carve.

Postcondition

Every anonymous spool and source descriptor is closed.

Optional PPM publication occurs only after full comparison and validation.

Since

0.1.0

Definition at line 595 of file ra8_fmt_portable_verify.c.

References ra8_fmt_cli_workspace_t::bytes, verify_cli_args_t::format, verify_cli_args_t::input, internal_execute(), internal_open_and_size(), internal_parse(), k_ra8_ok, k_verify_cli_fail, k_verify_cli_ok, priv_fmt_host_fd_sink(), RA8_PRIV, and strcmp().

Referenced by internal_dispatch().

Variable Documentation

s_failed_transaction_ops

const ra8_fmt_transaction_ops_t s_failed_transaction_ops

static

Initial value:

                                                                = {
  .append = internal_failed_append,
  .commit = internal_failed_commit,
  .abort  = internal_failed_abort,
}

Definition at line 353 of file ra8_fmt_portable_verify.c.

Referenced by internal_execute().