distributor/docs/internal/state.md

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. links is optional URL 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. Outputs may record url when the destination has link generation configured.

The optional top-level links.primary_url records the selected primary URL for the published destination bundle. It is omitted when link generation is not configured or when the destination primary policy has no matching output.

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.

Failure behavior

Invalid JSON, invalid state schema, invalid embedded source manifests, unsafe output paths, invalid stored URLs, unsupported output kinds, missing generated-output transform names, and mismatched pipeline or destination ids produce comparison outcomes that publish planning can turn into fail actions. Supported identity and source-manifest conflicts can become forced replacement only when publish planning receives explicit force and compatible transfer policy.

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.

Invariants

• .distributor.json is the destination sentinel and state record.
• Embedded source manifests use the same validation rules as source bundles.
• Generated outputs always record a transform id.
• Stored URLs are optional and must be absolute HTTP or HTTPS URLs when present.
• Comparison returns outcomes and reasons; it does not mutate storage.
• distributor_version is diagnostic metadata, not a comparison key.