Crate acta 

Acta v0.2 file validation and metadata reading.

validate checks a file’s framing, schema descriptors, and block metadata. validate_with_options can additionally decode every complete block and verify logical values and optional statistics. Reader exposes that same information as an open-time snapshot of the schema and the committed blocks. Both walk the file through one shared parser, so they agree about which files are well formed.

Logical block decoding is available through Reader::read_block, which decodes one whole block, and the lazy sequential Reader::scan API, which can restrict a read to a projection of the columns and to a half-open PrimaryRange over the primary column, pruning blocks by their stored bounds before reading them. A snapshot Scan is immutable: it decodes only the blocks the reader held when it was created, so later appends cannot enter it. To follow an append-only file as it grows, Reader::refresh extends the snapshot in place with frames committed since it was opened, and Reader::tail returns a Tail that polls the path for newly committed frames synchronously, one block per poll, without sleeping or blocking. A tail never exposes a partial frame, never infers a global primary ordering, and stops cleanly by being dropped. Writer creates deterministic plain/raw v0.2 files by default, buffers appended batches into blocks bounded by a row and a byte target, and can explicitly select Zstandard when the default zstd feature is enabled. Writer-side transforms, fixed policies, deterministic adaptive encoding, and optional block-local min/max statistics are available through additive writer options; their defaults leave the plain/raw output unchanged. Statistics are written under WriterStatistics, which is generation only: nothing reads them for pruning, since PrimaryRange prunes on the mandatory primary bounds in the block header. Writer::open reconstructs a complete existing file and resumes the same append engine that Writer::create enters, exposing the reconstructed schema through Writer::schema; Writer::open_with_schema adds an exact schema guard and Writer::open_with_limits reads the existing file under explicit Limits. Both entry points hold a cooperative exclusive writer lock that never blocks readers. Incomplete tails require explicit recovery and are not silently truncated. inspect_recovery is a read-only snapshot, while repair_incomplete_tail is a destructive operation narrowly limited to a structurally verified incomplete final data frame.

let report = acta::validate("spec/v0.2/fixtures/minimal/minimal.acta")?;

assert_eq!(report.format_version(), (0, 2));
assert_eq!(report.frame_count(), 2);
assert!(!report.incomplete_tail());

Explicit recovery is a read-only inspection followed by an intentional, narrowly bounded repair:

let path = std::path::Path::new("ticks.acta");
let plan = acta::inspect_recovery(path)?;
if plan.requires_repair() {
    let summary = acta::repair_incomplete_tail(path)?;
    println!("removed {} bytes", summary.bytes_removed());
}

Full validation is opt-in because it decodes every complete block and verifies optional statistics, while structural validation only walks the metadata needed to establish a safe snapshot.

Structs

BinaryArray

A binary array. FixedBinary uses the same representation and carries its width in the corresponding schema column.

BlockMetadata

Read-only metadata for one complete, committed data block.

Column

One immutable column in a Schema.

DecimalArray

A decimal64 array whose values are signed unscaled integers.

Error

An Acta error with a category, optional file offset, and parsing context.

FileMetadata

File-level metadata retained by a Reader snapshot.

Limits

Bounds checked against declared sizes before any file region is read.

PrimaryBounds

The inclusive primary timestamp/date bounds declared by one block.

PrimitiveArray

A typed fixed-width array with optional row validity.

Reader

A metadata-first, open-time snapshot of an Acta v0.2 file.

RecordBatch

A decoded block with one logical array per schema column.

RecoveryPlan

A read-only, point-in-time recovery decision for an Acta file.

RecoverySummary

The result of successfully repairing one incomplete final data frame.

RefreshReport

What one Reader::refresh added to a snapshot.

Scan

A lazy, sequential scan over the committed blocks in a reader snapshot.

ScanMetrics

Aggregate work counters for one scan. These expose only logical scan accounting; physical descriptor tables and decoder state remain private.

Schema

The fixed schema shared by every block in an Acta file.

Tail

A live tail over the frames appended after a reader’s snapshot.

TimestampArray

A timestamp64 array retaining its schema unit and timezone annotation.

Utf8Array

A UTF-8 array with one string slot per logical row.

ValidationOptions

Options controlling Acta validation.

ValidationReport

The result of a sequential Acta v0.2 structural validation.

WriteAccounting

A point-in-time view of writer data accounting.

WriteSummary

The result of a successfully finished writer.

Writer

A synchronous buffered writer for Acta v0.2 append sessions.

WriterOptions

Options for buffered Stage 7 writing.

Enums

Array

A logical column array. Each variant has exactly one value position per row; nullability is carried by the typed array’s validity bitmap.

ErrorContext

The region of a file an error was detected in.

ErrorKind

The broad category of an Acta failure.

LogicalType

A v0.2 logical column type.

PrimaryRange

A typed half-open range over the schema’s primary column.

RecoveryAction

The action a recovery inspection recommends.

ScalarValue

A borrowed logical scalar used by display and small native clients.

TimeUnit

The logical unit of a timestamp64 column.

TimeZone

The timezone annotation of a timestamp64 column.

ValidationLevel

The amount of an Acta file validation decodes.

WriterCodec

The stream codec selected by a crate::Writer.

WriterEncoding

The writer-side encoding policy.

WriterStatistics

The block-local min/max statistics policy selected by a crate::Writer.

WriterTransform

A value transform/layout that a writer can apply without profiling.

Constants

DEFAULT_BYTE_BLOCK_TARGET

The default maximum estimated raw frame size buffered into one data block.

DEFAULT_ROW_BLOCK_TARGET

The default maximum number of logical rows buffered into one data block.

DEFAULT_ZSTD_LEVEL

The default Zstandard compression level used by WriterOptions.

FILE_ID_SIZE

The width of the opaque file ID a v0.2 prologue carries.

Functions

inspect_recovery

Inspect recovery state without opening the file for writing.

inspect_recovery_with_limits

Inspect recovery state under caller-supplied structural limits.

repair_incomplete_tail

Repair a verified incomplete final data frame.

repair_incomplete_tail_with_limits

Repair a verified incomplete final data frame under structural limits.

validate

Validate the Acta v0.2 structure of path under the default Limits.

validate_with_limits

Validate the Acta v0.2 framing of path under caller-supplied limits.

validate_with_options

Validate an Acta file with an explicit level and resource limits.

Type Aliases

BooleanArray

A nullable boolean array.

Result

The result type returned by Acta operations.