# Parsley

> Causal delivery order for Kafka stream processing: a record reaches your processor only
> after every cause your processor consumes has been delivered locally. When A causally
> precedes B, every processor subscribed to both of their topics processes A before B.
> Causal safety is inviolable: Parsley blocks or fails, it never reorders, drops, or guesses
> on a timeout.

Parsley is a Java 21 library (Maven artifact, MIT license) for Kafka Streams applications
against brokers 3.7.0 or newer. The runtime dependencies are kafka-clients and kafka-streams,
both inherited; only the Streams adapter touches kafka-streams, and an application using just
the plain-client edge (CausalClock, CausalHeaders) can exclude it. The on-wire footprint is
three record headers (`vc`, `vc-sender`, `vc-seq`) on the application's own records; there
are no protocol records and plain consumers need no Parsley awareness. The primary
correctness gate is a deterministic simulator with a ground-truth causal oracle, run by
`mvn verify`. The full protocol is exercisable without a broker through
`Parsley.testTopology()` and Kafka Streams' `TopologyTestDriver`.

This file describes version 0.2.0-SNAPSHOT, the Maven artifact
`io.github.tobyjamesclements:parsley:0.2.0-SNAPSHOT`, resolved from the Central snapshots
repository (https://central.sonatype.com/repository/maven-snapshots/). Every link below
tracks the main branch, which matches 0.2.0-SNAPSHOT. On the versioned docs site these are
the pages served by the default `latest` alias, also addressable as `dev`. The 0.1.0
release, whose wire format and API differ from this version, stays addressable by its
version number.

## Foundations

- [The causal model](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/foundations/causal-model.md): the delivery invariant, its preconditions, and the happened-before relation on Kafka coordinates
- [The delivery gate](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/foundations/delivery-gate.md): per-channel FIFO hold queues, the delivered frontier, and the release cascade
- [Liveness](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/foundations/liveness.md): why every wait terminates, including under exactly-once transaction markers

## Design

- [Architecture](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/design/architecture.md): the functional core, the imperative edges, and the Kafka Streams adapter
- [State and recovery](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/design/state.md): what persists, under which keys, and how crash recovery restores it
- [Verification](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/design/verification.md): the simulator, the causal oracle, and the obligations the suite enforces

## Guide

- [Getting started](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/guide/getting-started.md): the coordinates, the snapshot repository, the resolved footprint, and declaring topics, stages, and running an application
- [Topology shapes](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/guide/topologies.md): pipelines, fan-in, fan-out, and cycles
- [Codecs and Avro](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/guide/codecs.md): typed topics and schema integration
- [Error handling](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/guide/error-handling.md): the error model and the recovering decorators
- [Ticks](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/guide/ticks.md): runtime-emitted time records delivered through the causal gate
- [The contract](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/guide/expectations.md): what Parsley promises and what it requires of the application
- [Diagnosing held records](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/guide/diagnosing-holds.md): explainHolds(), the vc-hold-* warnings, and what each diagnosis means — never fixed by skipping or a timeout
- [Verifying your application](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/guide/verifying.md): ContractProbes — the contract's checkable clauses as test-time and cluster probes
- [Plain clients](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/guide/clients.md): stamping from plain producers with CausalClock and incremental adoption

## Reference

- [Wire format](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/reference/wire-format.md): the record headers and state-store layouts; the compatibility surface
- [Conformance kit](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/reference/conformance-kit.md): the simulator and oracle as a consumable test-jar; the host contract, and how a vendored copy or alternative host verifies itself
- [Metrics](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/docs/reference/metrics.md): the vc-metrics group, gauges, and counters
- [README](https://raw.githubusercontent.com/tobyjamesclements/parsley/main/README.md): the one-page overview

## Optional

- [Every document above, concatenated](https://tobyjamesclements.github.io/parsley/llms-full.txt): the full text in one fetch, if you would rather not follow the links individually
- [Source repository](https://github.com/tobyjamesclements/parsley): single Maven module, one package; the public tier is codified in package-info.java