Checkpointed allocation-free pseudo-text source for block sweeps. More...

#include <string.h>
#include "sweep_block_internal.h"

Include dependency graph for sweep_block_payload.c:

Enumerations
enum	cbs_payload_limit_t : uint32_t { k_cbs_payload_checkpoint_bytes = 16384U , k_cbs_no_word = UINT32_MAX }
enum	cbs_payload_phase_t : uint8_t { k_cbs_phase_word = 0U , k_cbs_phase_dot , k_cbs_phase_newline , k_cbs_phase_space }
enum	cbs_payload_seed_t : uint64_t { k_cbs_payload_seed = 0x9E3779B97F4A7C15ULL }
enum	cbs_payload_shift_t : uint8_t { k_cbs_payload_shift_a = 13U , k_cbs_payload_shift_b = 7U , k_cbs_payload_shift_c = 17U }

Functions
static RA8_INTERNAL uint64_t	internal_payload_rng (uint64_t *state)
	Advance the deterministic payload pseudo-random generator.
static RA8_INTERNAL uint8_t	internal_payload_next (cbs_payload_state_t *state)
	Emit one byte from the deterministic pseudo-text state machine.
RA8_PRIV size_t	priv_payload_workspace_required (void)
	Return exact workspace bytes required by the pseudo-text source index.
RA8_PRIV int	priv_payload_init (cbs_payload_t payload, void workspace, size_t capacity)
	Build the payload source index into caller-owned storage.
RA8_PRIV ra8_err_t	priv_payload_read (void ctx, uint64_t offset, uint8_t buffer, uint32_t length)
	Read exact historical pseudo-text bytes at any bounded offset.

Variables
static const char *const	s_payload_words []

Detailed Description

Checkpointed allocation-free pseudo-text source for block sweeps.

Generates repeatable prose bytes from serialized checkpoints so arbitrary reads regenerate at most one bounded checkpoint span.

[Ring 7 / Tooling] {World: NS}

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

Since: 0.1.0

Definition in file sweep_block_payload.c.

Enumeration Type Documentation

◆ cbs_payload_limit_t

enum cbs_payload_limit_t : uint32_t

Enumerator
k_cbs_payload_checkpoint_bytes	Maximum seek regeneration.
k_cbs_no_word	Generator needs a new word.

Definition at line 17 of file sweep_block_payload.c.

◆ cbs_payload_phase_t

enum cbs_payload_phase_t : uint8_t

Enumerator
k_cbs_phase_word	Emit a word byte.
k_cbs_phase_dot	Emit a sentence period.
k_cbs_phase_newline	Emit a line break.
k_cbs_phase_space	Emit a word separator.

Definition at line 22 of file sweep_block_payload.c.

◆ cbs_payload_seed_t

enum cbs_payload_seed_t : uint64_t

Enumerator
k_cbs_payload_seed	Initial generator state.

Definition at line 29 of file sweep_block_payload.c.

◆ cbs_payload_shift_t

enum cbs_payload_shift_t : uint8_t

Enumerator
k_cbs_payload_shift_a	First xorshift distance.
k_cbs_payload_shift_b	Middle xorshift distance.
k_cbs_payload_shift_c	Final xorshift distance.

Definition at line 33 of file sweep_block_payload.c.

Function Documentation

◆ internal_payload_next()

RA8_INTERNAL uint8_t internal_payload_next ( cbs_payload_state_t * state )

static

Emit one byte from the deterministic pseudo-text state machine.

Selects words through internal_payload_rng and inserts bounded spaces, periods, and newlines according to the sentence phase.

Parameters

[in,out] state Generator cursor to advance by one output byte.

Returns: Next deterministic payload byte.

Return values

other ASCII word or separator byte.

Precondition: state is non-NULL and initialized from the payload seed.; state->phase is a valid cbs_payload_phase_t value.

Postcondition: The returned byte matches the advanced state position.; Exactly one logical payload byte is consumed.

Note: Thread-safe for distinct generator states.

Since: 0.1.0

Definition at line 86 of file sweep_block_payload.c.

References internal_payload_rng(), k_cbs_no_word, k_cbs_phase_dot, k_cbs_phase_newline, k_cbs_phase_space, k_cbs_phase_word, k_cbs_words_per_dot, cbs_payload_state_t::phase, cbs_payload_state_t::rng, s_payload_words, cbs_payload_state_t::sentence_words, cbs_payload_state_t::word_index, and cbs_payload_state_t::word_offset.

Referenced by priv_payload_init(), and priv_payload_read().

◆ internal_payload_rng()

RA8_INTERNAL uint64_t internal_payload_rng ( uint64_t * state )

static

Advance the deterministic payload pseudo-random generator.

Applies the fixed xorshift sequence and stores the new state for reproducible word selection at every checkpoint.

Parameters

[in,out] state Non-zero generator state.

Returns: Updated 64-bit pseudo-random value.

Return values

other Deterministic next value in the xorshift sequence.

Precondition: state is non-NULL and points to writable storage.; The initial seed is non-zero.

Postcondition: *state equals the returned value.; No state outside state is modified.

Note: This generator is for repeatable workload bytes, not cryptography.

Since: 0.1.0

Definition at line 61 of file sweep_block_payload.c.

References k_cbs_payload_shift_a, k_cbs_payload_shift_b, and k_cbs_payload_shift_c.

Referenced by internal_payload_next().

◆ priv_payload_init()

RA8_PRIV int priv_payload_init	(	cbs_payload_t *	payload,
		void *	workspace,
		size_t	capacity )

Build the payload source index into caller-owned storage.

Serializes deterministic generator state at each bounded seek span and initializes the sequential cursor at offset zero.

Parameters

[out]	payload	Payload binding to initialize.
[in,out]	workspace	Aligned caller-owned checkpoint storage.
[in]	capacity	Supplied workspace byte count.

Returns: Zero on success, otherwise one.

Return values

0	`payload` is ready for exact reads.
1	A binding, alignment, or capacity check failed.

Precondition: payload and workspace are non-NULL.; workspace is aligned for cbs_payload_state_t.

Postcondition: On success, every checkpoint is initialized deterministically.; Workspace ownership remains with the caller.

Note: Initialization is bounded by fixed payload geometry.

Since: 0.1.0

Definition at line 132 of file sweep_block_payload.c.

References internal_payload_next(), k_cbs_no_word, k_cbs_payload_checkpoint_bytes, k_cbs_payload_seed, and priv_payload_workspace_required().

Referenced by cb_sweep_block().

◆ priv_payload_read()

RA8_PRIV ra8_err_t priv_payload_read	(	void *	ctx,
		uint64_t	offset,
		uint8_t *	buffer,
		uint32_t	length )

Read exact historical pseudo-text bytes at any bounded offset.

Restores the nearest checkpoint when needed, regenerates at most one checkpoint span, and caches the resulting sequential cursor.

Parameters

[in,out]	ctx	Bound cbs_payload_t.
[in]	offset	Logical payload offset.
[out]	buffer	Destination buffer.
[in]	length	Exact byte count.

Returns: Repository error code.

Return values

k_ra8_ok	The complete range was generated.
k_ra8_err_null_ptr	A required binding is NULL.
k_ra8_err_out_of_range	The requested range exceeds the fixed payload.

Precondition: buffer is writable for length bytes.; ctx was initialized by priv_payload_init.

Postcondition: On success, buffer contains the deterministic historical bytes.; The cached cursor names the end of the completed read.

Note: Distinct payload bindings may be read independently.

Since: 0.1.0

Definition at line 158 of file sweep_block_payload.c.

References cbs_payload_t::checkpoint_count, cbs_payload_t::checkpoints, cbs_payload_t::cursor_offset, cbs_payload_t::cursor_state, internal_payload_next(), k_cbs_blob_bytes, k_cbs_payload_checkpoint_bytes, k_ra8_err_null_ptr, k_ra8_err_out_of_range, and k_ra8_ok.

Referenced by internal_execute().

◆ priv_payload_workspace_required()

RA8_PRIV size_t priv_payload_workspace_required ( void )

Return exact workspace bytes required by the pseudo-text source index.

Sizes one serialized generator checkpoint per bounded regeneration span.

Returns: Exact checkpoint-index byte count.

Return values

other Non-zero fixed payload-index requirement.

Precondition: Fixed payload and checkpoint geometries are internally consistent.; sizeof(cbs_payload_state_t) fits in size_t multiplication.

Postcondition: The result covers all checkpoints including offset zero.; No storage or global state is modified.

Note: Thread-safe: this is fixed-geometry arithmetic.

Since: 0.1.0

Definition at line 125 of file sweep_block_payload.c.

References k_cbs_blob_bytes, and k_cbs_payload_checkpoint_bytes.

Referenced by cb_sweep_block(), and priv_payload_init().

Variable Documentation

◆ s_payload_words

const char* const s_payload_words[]

static

Initial value:

                                        = {
  "the",     "quick",   "reader", "turns",   "another", "page",    "while",   "morning",
  "light",   "settles", "across", "quiet",   "margins", "and",     "chapter", "headings",
  "gather",  "small",   "notes",  "between", "lines",   "of",      "steady",  "prose",
  "carried", "through", "paper",  "towns",   "by",      "patient", "hands",   "again",
}

Definition at line 39 of file sweep_block_payload.c.

Referenced by internal_payload_next().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ cbs_payload_limit_t

◆ cbs_payload_phase_t

◆ cbs_payload_seed_t

◆ cbs_payload_shift_t

Function Documentation

◆ internal_payload_next()

◆ internal_payload_rng()

◆ priv_payload_init()

◆ priv_payload_read()

◆ priv_payload_workspace_required()

Variable Documentation

◆ s_payload_words