No-heap implementation of the backing-agnostic JOF audit. More...

#include "jof_audit.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"

Include dependency graph for jof_audit.c:

Data Structures
struct	internal_span_t
	Half-open address span used for caller-buffer separation checks. More...
struct	internal_audit_context_t
	Mutable state shared by the bounded per-tile audit operation. More...

Typedefs
typedef struct internal_span_t	internal_span_t
	Half-open address span used for caller-buffer separation checks.
typedef struct internal_audit_context_t	internal_audit_context_t
	Mutable state shared by the bounded per-tile audit operation.

Enumerations
enum	jof_audit_hash_t : uint32_t { k_jof_audit_fnv_basis = 2166136261U , k_jof_audit_fnv_prime = 16777619U , k_jof_audit_u32_b3_shift = 24U }
	FNV-1a constants used for decoded tile evidence. More...

Functions
static ra8_err_t	internal_read_exact (jof_pread_fn pread, void ctx, uint64_t offset, uint8_t buf, size_t len)
	Read exactly one bounded window from the injected backing.
static uint32_t	internal_rd_u32 (const uint8_t *p)
	Decode a little-endian u32 from an index entry.
static uint32_t	internal_hash (const uint8_t bytes, size_t len, bool out_uniform)
	Hash decoded bytes and report whether all bytes are equal.
static ra8_err_t	internal_make_span (const void ptr, size_t len, internal_span_t out)
	Convert one caller region into an overflow-checked address span.
static bool	internal_spans_overlap (const internal_span_t left, const internal_span_t right)
	Report whether two non-wrapping half-open spans overlap.
static bool	internal_any_workspace_overlap (const internal_span_t workspace, const internal_span_t records, const internal_span_t tile, const internal_span_t scratch, const internal_span_t *result)
	Check every pair of writable audit spans for overlap.
ra8_err_t	jof_audit_requirements (jof_pread_fn pread, void pread_ctx, uint64_t total_size, jof_audit_requirements_t out)
	Parse an atlas and report exact caller-storage requirements.
static ra8_err_t	internal_check_workspace_spans (const jof_audit_workspace_t ws, const jof_audit_requirements_t need, const jof_audit_result_t *out, size_t record_bytes)
	Validate the writable audit span layout.
static ra8_err_t	internal_check_workspace (const jof_audit_workspace_t ws, const jof_audit_requirements_t need, const jof_audit_result_t *out)
	Validate caller workspace against parsed requirements.
static uint32_t	internal_duplicate_count (const jof_audit_record_t records, uint32_t count, const jof_audit_record_t item)
	Count earlier records matching one non-uniform tile fingerprint.
static ra8_err_t	internal_audit_tile (internal_audit_context_t *context, uint32_t index_number)
	Audit one index entry and its decoded tile evidence.
ra8_err_t	jof_audit (jof_pread_fn pread, void pread_ctx, uint64_t total_size, jof_audit_workspace_t workspace, jof_audit_result_t *out)
	Audit coverage, geometry and duplicate-content evidence in bounded RAM.

Detailed Description

No-heap implementation of the backing-agnostic JOF audit.

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

Parses JOF geometry through an injected positioned-read backend, derives exact caller-buffer requirements, and audits every indexed tile for stored coverage and decoded-size consistency. Reused caller scratch supports raw and compressed payloads without allocation or a filesystem dependency.

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

Since: 0.1.0

Definition in file jof_audit.c.

Typedef Documentation

◆ internal_audit_context_t

typedef struct internal_audit_context_t internal_audit_context_t

Mutable state shared by the bounded per-tile audit operation.

◆ internal_span_t

typedef struct internal_span_t internal_span_t

Half-open address span used for caller-buffer separation checks.

Enumeration Type Documentation

◆ jof_audit_hash_t

enum jof_audit_hash_t : uint32_t

FNV-1a constants used for decoded tile evidence.

Enumerator
k_jof_audit_fnv_basis	FNV-1a 32-bit offset basis.
k_jof_audit_fnv_prime	FNV-1a 32-bit prime.
k_jof_audit_u32_b3_shift	LE32 high-byte shift.

Definition at line 29 of file jof_audit.c.

Function Documentation

◆ internal_any_workspace_overlap()

bool internal_any_workspace_overlap	(	const internal_span_t *	workspace,
		const internal_span_t *	records,
		const internal_span_t *	tile,
		const internal_span_t *	scratch,
		const internal_span_t *	result )

static

Check every pair of writable audit spans for overlap.

Evaluates the ten unique pairs in a fixed order and stops at the first shared byte, including the result and workspace descriptors.

Parameters

[in]	workspace	Workspace descriptor span.
[in]	records	Record-array span.
[in]	tile	Decoded-tile span.
[in]	scratch	Codec-scratch span, possibly empty.
[in]	result	Public result span.

Returns: Whether any supplied pair overlaps.

Return values

true	At least one pair shares a byte.
false	Every pair is disjoint.

Precondition: Every span came from internal_make_span.; All span objects are non-NULL and readable.

Postcondition: No span or caller storage is modified.; False proves pairwise separation of all five spans.

Note: Empty spans compare disjoint from every span.

Since: 0.1.0

Definition at line 201 of file jof_audit.c.

References internal_spans_overlap(), and RA8_INTERNAL.

Referenced by internal_check_workspace_spans().

◆ internal_audit_tile()

ra8_err_t internal_audit_tile	(	internal_audit_context_t *	context,
		uint32_t	index_number )

static

Audit one index entry and its decoded tile evidence.

Reads the canonical record, checks stored coverage, decodes through caller scratch, validates edge geometry, and accumulates diagnostic evidence.

Parameters

[in,out]	context	Mutable bounded audit state and caller workspaces.
[in]	index_number	Zero-based index record to audit.

Returns: Canonical read, decode, or validation status.

Return values

k_ra8_ok	One record and its tile evidence were completed.
k_ra8_err_validation_failed	Stored offset arithmetic was invalid.
other	Injected read, tile decode, or dimension derivation failed.

Precondition: context is non-null and all workspace spans passed overlap checks.; index_number is below the parsed tile count and record capacity.

Postcondition: Success initializes exactly the selected record and advances coverage.; Failure never increments the decoded-tile count for an incomplete tile.

Note: Duplicate fingerprints are diagnostic candidates, not equality proof.

Since: 0.1.0

Definition at line 451 of file jof_audit.c.

References jof_info_t::bpp, internal_audit_context_t::candidate, jof_audit_record_t::content_hash, jof_audit_result_t::coverage_errors, jof_audit_result_t::decoded_tiles, jof_audit_result_t::duplicate_candidates, internal_audit_context_t::expected_offset, jof_audit_result_t::geometry_errors, jof_audit_record_t::height, jof_info_t::index_off, jof_audit_result_t::info, internal_duplicate_count(), internal_hash(), internal_rd_u32(), internal_read_exact(), jof_read_tile(), jof_tile_dims(), k_jof_idx_ofs_length, k_jof_idx_ofs_offset, k_jof_index_entry, k_ra8_err_validation_failed, k_ra8_ok, jof_audit_record_t::length, jof_audit_record_t::offset, jof_audit_record_t::payload, internal_audit_context_t::pread, internal_audit_context_t::pread_ctx, jof_audit_workspace_t::records, jof_audit_workspace_t::scratch, jof_audit_workspace_t::scratch_cap, jof_audit_workspace_t::tile, jof_audit_workspace_t::tile_cap, jof_info_t::tile_cols, jof_audit_record_t::uniform, jof_audit_record_t::width, and internal_audit_context_t::workspace.

Referenced by jof_audit().

◆ internal_check_workspace()

ra8_err_t internal_check_workspace	(	const jof_audit_workspace_t *	ws,
		const jof_audit_requirements_t *	need,
		const jof_audit_result_t *	out )

static

Validate caller workspace against parsed requirements.

Checks every mandatory pointer and exact-or-larger capacity.

Parameters

[in]	ws	Caller workspace.
[in]	need	Exact requirements.
[in]	out	Public result destination.

Returns: Workspace validation status.

Return values

k_ra8_ok	All required spans are present and large enough.
k_ra8_err_null_ptr	A mandatory span is absent.
k_ra8_err_invalid_size	At least one capacity is too small.
k_ra8_err_invalid_arg	Writable caller spans overlap.

Precondition: need points to successfully derived requirements.; ws is either null or points to readable workspace metadata.

Postcondition: No caller buffer contents are modified.; Success authorizes exactly the capacities in need.

Note: Thread-safe and allocation-free.

Since: 0.1.0

Definition at line 348 of file jof_audit.c.

References internal_check_workspace_spans(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, RA8_INTERNAL, jof_audit_workspace_t::record_cap, jof_audit_requirements_t::record_count, jof_audit_workspace_t::records, jof_audit_workspace_t::scratch, jof_audit_requirements_t::scratch_bytes, jof_audit_workspace_t::scratch_cap, jof_audit_workspace_t::tile, jof_audit_requirements_t::tile_bytes, and jof_audit_workspace_t::tile_cap.

Referenced by jof_audit().

◆ internal_check_workspace_spans()

ra8_err_t internal_check_workspace_spans	(	const jof_audit_workspace_t *	ws,
		const jof_audit_requirements_t *	need,
		const jof_audit_result_t *	out,
		size_t	record_bytes )

static

Validate the writable audit span layout.

Builds checked integer spans for every caller-owned destination and rejects arithmetic overflow or any pairwise overlap.

Parameters

[in]	ws	Caller workspace.
[in]	need	Exact requirements.
[in]	out	Public result destination.
[in]	record_bytes	Size of the complete record array.

Returns: Span validation status.

Return values

k_ra8_ok	Every writable span is representable and disjoint.
k_ra8_err_invalid_size	A span end cannot be represented.
k_ra8_err_invalid_arg	At least two writable spans overlap.

Precondition: All required workspace pointers and capacities are already validated.; record_bytes is the checked record-array byte count.

Postcondition: No caller buffer contents are modified.; Success proves pairwise separation of all writable destinations.

Note: Thread-safe and allocation-free.

Since: 0.1.0

Definition at line 294 of file jof_audit.c.

References internal_any_workspace_overlap(), internal_make_span(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_INTERNAL, jof_audit_workspace_t::records, jof_audit_workspace_t::scratch, jof_audit_requirements_t::scratch_bytes, jof_audit_workspace_t::tile, and jof_audit_requirements_t::tile_bytes.

Referenced by internal_check_workspace().

◆ internal_duplicate_count()

uint32_t internal_duplicate_count	(	const jof_audit_record_t *	records,
		uint32_t	count,
		const jof_audit_record_t *	item )

static

Count earlier records matching one non-uniform tile fingerprint.

Uniform tiles are excluded so common blank regions do not inflate duplicate diagnostics; matching hashes are evidence only.

Parameters

[in]	records	Completed records.
[in]	count	Earlier record count.
[in]	item	Current record.

Returns: Number of matching earlier records, as diagnostic candidates only.

Return values

0	The item is uniform or no earlier fingerprint matches.

Precondition: records contains count completed entries.; item points to one completed current entry.

Postcondition: The record array and item are unchanged.; The result never exceeds count.

Note: A fingerprint match is not byte-equality proof and cannot invalidate an otherwise well-formed atlas.

Since: 0.1.0

Definition at line 401 of file jof_audit.c.

References jof_audit_record_t::content_hash, jof_audit_record_t::payload, RA8_INTERNAL, and jof_audit_record_t::uniform.

Referenced by internal_audit_tile().

◆ internal_hash()

uint32_t internal_hash	(	const uint8_t *	bytes,
		size_t	len,
		bool *	out_uniform )

static

Hash decoded bytes and report whether all bytes are equal.

Produces bounded FNV-1a diagnostic evidence, not an identity proof.

Parameters

[in]	bytes	Decoded tile.
[in]	len	Tile byte count.
[out]	out_uniform	Receives uniformity evidence.

Returns: FNV-1a hash.

Return values

k_jof_audit_fnv_basis Hash returned for an empty span.

Precondition: bytes is readable for len bytes.; out_uniform is writable.

Postcondition: out_uniform is true exactly when every byte equals the first.; The input bytes are unchanged.

Note: Thread-safe and allocation-free.

Since: 0.1.0

Definition at line 104 of file jof_audit.c.

References k_jof_audit_fnv_basis, k_jof_audit_fnv_prime, and RA8_INTERNAL.

Referenced by internal_audit_tile().

◆ internal_make_span()

ra8_err_t internal_make_span	(	const void *	ptr,
		size_t	len,
		internal_span_t *	out )

static

Convert one caller region into an overflow-checked address span.

Empty spans are represented by zero endpoints and never overlap.

Parameters

[in]	ptr	Region start, or null only when `len` is zero.
[in]	len	Region byte count.
[out]	out	Receives the half-open address span.

Returns: Span-construction status.

Return values

k_ra8_ok	The span is representable.
k_ra8_err_null_ptr	A non-empty span has no storage.
k_ra8_err_invalid_size	The end address would wrap.

Precondition: out is non-null and writable.; A non-empty ptr denotes at least len bytes of caller storage.

Postcondition: Success initializes out without touching caller storage.; Failure does not dereference ptr.

Note: Thread-safe and allocation-free.

Since: 0.1.0

Definition at line 138 of file jof_audit.c.

References k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, memcpy(), and RA8_INTERNAL.

Referenced by internal_check_workspace_spans().

◆ internal_rd_u32()

uint32_t internal_rd_u32 ( const uint8_t * p )

static

Decode a little-endian u32 from an index entry.

Combines four bytes explicitly so host endianness is irrelevant.

Parameters

[in] p Four readable bytes.

Returns: Decoded value.

Return values

0	All four encoded bytes were zero.

Precondition: p addresses at least four readable bytes.; The bytes use the canonical JOF little-endian order.

Postcondition: The source bytes are unchanged.; The return value is independent of native integer representation.

Note: Thread-safe and allocation-free.

Since: 0.1.0

Definition at line 83 of file jof_audit.c.

References k_jof_audit_u32_b3_shift, and RA8_INTERNAL.

Referenced by internal_audit_tile().

◆ internal_read_exact()

ra8_err_t internal_read_exact	(	jof_pread_fn	pread,
		void *	ctx,
		uint64_t	offset,
		uint8_t *	buf,
		size_t	len )

static

Read exactly one bounded window from the injected backing.

Converts a short successful callback read into a validation error.

Parameters

[in]	pread	Read callback.
[in]	ctx	Callback context.
[in]	offset	Absolute offset.
[out]	buf	Destination.
[in]	len	Exact byte count.

Returns: Exact-read status.

Return values

k_ra8_ok	Exactly `len` bytes were read.
k_ra8_err_validation_failed	The callback returned a short read.

Precondition: pread and buf are non-null.; buf is writable for len bytes.

Postcondition: Success initializes exactly len bytes in buf.; Failure never claims a complete read.

Note: Thread safety inherits the injected reader.

Since: 0.1.0

Definition at line 60 of file jof_audit.c.

References k_ra8_err_validation_failed, and k_ra8_ok.

Referenced by internal_audit_tile().

◆ internal_spans_overlap()

bool internal_spans_overlap	(	const internal_span_t *	left,
		const internal_span_t *	right )

static

Report whether two non-wrapping half-open spans overlap.

Uses strict half-open comparisons so adjacent and empty spans are treated as disjoint while any shared byte is rejected.

Parameters

[in]	left	First checked span.
[in]	right	Second checked span.

Returns: True only when the spans share at least one byte.

Return values

true	The spans overlap.
false	The spans are disjoint or at least one is empty.

Precondition: Both spans came from internal_make_span.; left and right are non-null readable objects.

Postcondition: Neither span is modified.; The result depends only on the two endpoint pairs.

Note: Thread-safe and allocation-free.

Since: 0.1.0

Definition at line 173 of file jof_audit.c.

References internal_span_t::begin, internal_span_t::end, and RA8_INTERNAL.

Referenced by internal_any_workspace_overlap().

◆ jof_audit()

ra8_err_t jof_audit	(	jof_pread_fn	pread,
		void *	pread_ctx,
		uint64_t	total_size,
		jof_audit_workspace_t *	workspace,
		jof_audit_result_t *	out )

nodiscard

Audit coverage, geometry and duplicate-content evidence in bounded RAM.

Parses and decodes every indexed tile through the shared JOF reader, verifies exact stored-stream coverage and decoded dimensions, and records diagnostic duplicate fingerprints without treating a hash match as proof.

Parameters

[in]	pread	Positioned-read backend.
[in]	pread_ctx	Backend context.
[in]	total_size	Complete atlas byte length.
[in,out]	workspace	Exact-or-larger caller-owned buffers.
[out]	out	Receives parsed geometry and anomaly counts.

Returns: Audit status.

Return values

k_ra8_ok	The atlas passed every structural audit.
k_ra8_err_validation_failed	Coverage or geometry is inconsistent.
k_ra8_err_null_ptr	A callback, output, or required workspace is null.
k_ra8_err_invalid_size	A caller workspace is too small.
k_ra8_err_invalid_arg	Writable workspace or result spans overlap.

Precondition: Capacities satisfy jof_audit_requirements for the same backing.; Workspace spans and out remain exclusively owned during the call; overlap is rejected before any workspace or output byte is changed.

Postcondition: The function performs no allocation and retains no caller pointer.; Success reports one decoded record for every parsed tile.; A complete structural audit publishes diagnostics on success or validation failure; callback/decode failures preserve out.

Note: Matching tile hashes increment jof_audit_result_t::duplicate_candidates for diagnostics, but never reject an atlas: repeated image tiles are valid and a hash match alone is not proof that two decoded tiles are identical.

Since: 0.1.0

Definition at line 513 of file jof_audit.c.

References jof_audit_result_t::coverage_errors, internal_audit_context_t::expected_offset, jof_audit_result_t::geometry_errors, jof_info_t::index_off, jof_audit_result_t::info, internal_audit_tile(), internal_check_workspace(), jof_audit_requirements(), jof_parse(), k_jof_hdr_bytes, k_ra8_err_null_ptr, k_ra8_err_validation_failed, k_ra8_ok, and jof_info_t::tile_count.

Referenced by ra8_fmt_jof_inspect_stream().

◆ jof_audit_requirements()

ra8_err_t jof_audit_requirements	(	jof_pread_fn	pread,
		void *	pread_ctx,
		uint64_t	total_size,
		jof_audit_requirements_t *	out )

nodiscard

Parse an atlas and report exact caller-storage requirements.

Validates the JOF header/footer/index geometry through the injected reader and derives the exact record, decoded-tile, and compressed-scratch capacities needed by jof_audit.

Parameters

[in]	pread	Positioned-read backend.
[in]	pread_ctx	Backend context.
[in]	total_size	Complete atlas byte length.
[out]	out	Receives exact capacities.

Returns: Requirement-query status.

Return values

k_ra8_ok	Exact capacities were published.
k_ra8_err_null_ptr	A callback or output pointer is null.
k_ra8_err_invalid_size	Parsed geometry cannot fit bounded capacities.

Precondition: pread reads only from the immutable object described by total_size.; out is writable and does not alias the backing object.

Postcondition: No dynamic allocation or backend mutation occurs.; Failure does not publish a usable requirements record.

Note: Thread-safe when the injected reader and backing are thread-safe.

Since: 0.1.0

Definition at line 237 of file jof_audit.c.

References jof_info_t::bpp, jof_info_t::codec, jof_parse(), jof_stored_bound(), k_jof_codec_deflate, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, jof_audit_requirements_t::scratch_bytes, jof_audit_requirements_t::tile_bytes, jof_info_t::tile_count, jof_info_t::tile_h, and jof_info_t::tile_w.

Referenced by internal_run_jof(), and jof_audit().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ internal_audit_context_t

◆ internal_span_t

Enumeration Type Documentation

◆ jof_audit_hash_t

Function Documentation

◆ internal_any_workspace_overlap()

◆ internal_audit_tile()

◆ internal_check_workspace()

◆ internal_check_workspace_spans()

◆ internal_duplicate_count()

◆ internal_hash()

◆ internal_make_span()

◆ internal_rd_u32()

◆ internal_read_exact()

◆ internal_spans_overlap()

◆ jof_audit()

◆ jof_audit_requirements()