distributor/docs/internal/state.md

# Destination State Internals

Audience: developers and LLM coding agents changing `internal/state`.

## Purpose

`internal/state` parses, validates, serializes, and compares `.distributor.json` destination state.

## Inputs And Outputs

Inputs are destination state JSON, constructed state values, current source manifest, pipeline id, destination id, and whether the destination path has content without state. Outputs are validated state values, JSON bytes, comparison outcomes, and human-readable reasons.

## Boundaries

The package does not inspect storage backends, mutate files, choose transfer policy, build publish outputs, generate URLs, or parse config. Publish planning consumes state comparison outcomes.

The external destination state contract is documented in `docs/integrations/destination-state.md`.

## Config Fields Used

None directly. Destination ids, pipeline ids, and link URLs originate from config but are supplied as values by callers.

## Adapters Used

None.

## State And Manifest Behavior

`.distributor.json` schema version is `1`. Required fields are `pipeline_id`, `destination_id`, `published_at`, `source.manifest`, and `outputs`. `distributor_version` and `links` are optional.

Embedded source manifests are parsed and validated through `internal/bundle`, which delegates source manifest semantics to `pkg/bundle`. Output records require clean paths, `source` or `generated` kind, valid source paths, lowercase SHA-256 digests, non-negative sizes, and transform ids for generated outputs. Stored URLs must pass `internal/link` validation.

## Skip And Resume Behavior

Comparison is pure. It returns outcomes for absent state, unmanaged content, invalid state, pipeline/destination mismatch, same source manifest, older destination, newer destination, same-created digest conflict, and different source id conflict. It does not decide whether to skip, replace, force, or fail; publish planning maps outcomes to actions.

## Failure Behavior

Parsing rejects invalid JSON, trailing data, missing required fields, invalid timestamps, invalid embedded manifests, duplicate outputs, invalid output paths, unsupported output kinds, missing generated transforms, invalid URLs, invalid digests, and negative sizes.

## Tests To Inspect

- `internal/state/distributor_test.go`
- `internal/state/compare_test.go`
- `internal/publish/*_test.go`

## Architectural Invariants

- `.distributor.json` is the destination sentinel and state record.
- Comparison does not mutate storage.
- Embedded source manifests use the source bundle contract.
- Generated outputs always record a transform id.
- Stored URLs are optional and must be absolute HTTP or HTTPS URLs when present.
- `distributor_version` is diagnostic metadata, not a comparison key.