object-log 0.4.0

A buffered, multiplexing append log over pluggable object storage, with a sequencing seam (opaque payloads, durable-on-return writes, group-commit).
Documentation
# Contributing to object-log

Thanks for your interest in improving object-log! This is a small, focused crate
— an append-only log core over a pluggable object store — and contributions that
keep it small and well-tested are very welcome.

## Development

Requires Rust **1.88+** (edition 2024; MSRV in `Cargo.toml`). Before opening a
PR, please run the same checks CI runs:

```sh
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
```

All public items must be documented (the crate sets `#![deny(missing_docs)]`).

### Optional: diagnostics / black-box CLI

```sh
cargo run --features cli --bin object-log -- --help
printf 'a\nb\n' | cargo run --features cli --bin object-log -- \
  produce --root /tmp/olog --partition t --lines
cargo run --features cli --bin object-log -- \
  consume --root /tmp/olog --partition t --lines
cargo test --features cli --test cli_smoke
```

### Optional: live S3 operator evidence

Hermetic unit tests never require S3. CI runs MinIO automatically (`s3-minio`
job). To record **provider evidence** (and get a paste-ready TD-002 row):

```sh
./scripts/s3-evidence.sh minio
OBJECT_LOG_S3_KEY_ID=… OBJECT_LOG_S3_SECRET=… ./scripts/s3-evidence.sh garage
# AWS / R2:
OBJECT_LOG_S3_ENDPOINT=… OBJECT_LOG_S3_BUCKET=… \
OBJECT_LOG_S3_KEY_ID=… OBJECT_LOG_S3_SECRET=… \
  ./scripts/s3-evidence.sh aws
```

Paste the printed markdown row into
`docs/helix/02-design/technical-designs/TD-002-s3-adapter-retention-and-snapshots.md`
(evidence log). Legacy `FJORD_GARAGE_*` env names still work.

### Optional: honest local throughput

CI runs a release-mode floor (`perf` job, 16 MiB). Locally:

```sh
cargo test --release --test perf_throughput honest -- --nocapture
# larger sample:
OBJECT_LOG_PERF_BYTES=$((256*1024*1024)) cargo test --release --test perf_throughput honest -- --nocapture
```

## Guidelines

- Keep the dependency footprint minimal.
- New behavior should come with tests. Prefer the engine / BlobStore /
  sequencer suites under `tests/` (`engine`, `blob`, `sequencer_conformance`).
- Discuss larger changes (new traits, layout changes) in an issue first.
  Payload framing is consumer-owned; do not add Kafka or product schemas to core.

## Reporting bugs / security issues

Open a GitHub issue for bugs. For anything security-sensitive (e.g. a way to make
the segment decoder panic or read out of bounds on untrusted input), please
report it privately to the maintainer rather than in a public issue.

## License

By contributing, you agree that your contributions will be dual-licensed under
the MIT and Apache-2.0 licenses, as described in `README.md`, without any
additional terms or conditions.