No-heap, backing-agnostic structural audit for JOF atlases. More...

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

Include dependency graph for jof_audit.h:

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

Data Structures
struct	jof_audit_record_t
	One decoded tile's stored window and content evidence. More...
struct	jof_audit_requirements_t
	Exact caller-storage requirements derived from a parsed atlas. More...
struct	jof_audit_workspace_t
	Caller-owned buffers consumed by one audit. More...
struct	jof_audit_result_t
	Geometry plus anomaly counts emitted by a complete audit. More...

Typedefs
typedef struct jof_audit_record_t	jof_audit_record_t
typedef struct jof_audit_requirements_t	jof_audit_requirements_t
typedef struct jof_audit_workspace_t	jof_audit_workspace_t
typedef struct jof_audit_result_t	jof_audit_result_t

Functions
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.
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, backing-agnostic structural audit for JOF atlases.

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

This library-domain engine reads through jof_pread_fn and borrows every record and decode buffer from its caller. The same code therefore audits a host file, VFS stream, SD entry, or RAM image without libc file APIs or allocation. Host tools are adapters to this contract rather than owners of a second JOF implementation.

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

Since: 0.1.0

Definition in file jof_audit.h.

Typedef Documentation

◆ jof_audit_record_t

typedef struct jof_audit_record_t jof_audit_record_t

◆ jof_audit_requirements_t

typedef struct jof_audit_requirements_t jof_audit_requirements_t

◆ jof_audit_result_t

typedef struct jof_audit_result_t jof_audit_result_t

◆ jof_audit_workspace_t

typedef struct jof_audit_workspace_t jof_audit_workspace_t

Function Documentation

◆ 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

Functions