Document internal component contracts

docs/internal/state.md

@@ -31,6 +31,10 @@ Each output records `path`, `kind`, `source_path`, `sha256`, and `size`. Support
 
 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, 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.
+
 ## Boundaries
 
 This package does not publish files, delete files, inspect storage backends, or choose transfer policy actions. Publish planning consumes these comparison outcomes later.
@@ -38,3 +42,11 @@ This package does not publish files, delete files, inspect storage backends, or
 ## 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.
+- Comparison returns outcomes and reasons; it does not mutate storage.
+- `distributor_version` is diagnostic metadata, not a comparison key.