Add destination state comparison

docs/internal/state.md

@@ -0,0 +1,40 @@
+# Destination State
+
+## Purpose
+
+`internal/state` parses, validates, writes, and compares `.distributor.json` destination state.
+
+## Inputs and outputs
+
+Input is JSON destination state plus the current source manifest, pipeline id, destination id, and whether the destination path has unmanaged content. Output is a deterministic comparison outcome and reason.
+
+## State behavior
+
+`.distributor.json` requires:
+
+- `schema_version: 1`
+- `pipeline_id`
+- `destination_id`
+- `published_at`
+- `source.manifest`
+- `outputs`
+
+`distributor_version` is optional diagnostic metadata. `published_at` parses as RFC3339 and distributor-written state serializes it as RFC3339 UTC.
+
+The embedded `source.manifest` is validated with the same source manifest rules used by `internal/bundle`.
+
+## Outputs
+
+Each output records `path`, `kind`, `source_path`, `sha256`, and `size`. Supported output kinds are `source` and `generated`. Generated outputs require `transform`.
+
+## Comparison
+
+Comparison outcomes cover absent destination state, unmanaged destination content, invalid state, pipeline or destination mismatch, same source manifest, older destination source, newer destination source, same-created digest conflict, and different source id conflict.
+
+## Boundaries
+
+This package does not publish files, delete files, inspect storage backends, or choose transfer policy actions. Publish planning consumes these comparison outcomes later.
+
+## Tests
+
+Before changing destination state behavior, inspect tests under `internal/state`.