Document reconciliation modes

docs/config.md

@@ -35,7 +35,7 @@ pipelines:
         path: /srv/reports/archive
 ```
 
-This config publishes source files only. It uses default validation, destination path mapping, publish, transfer, and HTTP server values.
+This config publishes source files only. It uses default validation, destination path mapping, publish, reconciliation, transfer, and HTTP server values.
 
 ## Production-Oriented Local Config
 
@@ -66,6 +66,8 @@ pipelines:
           html: false
         path_mapping:
           mode: preserve_relative
+        reconciliation:
+          mode: replace
         transfer:
           on_destination_same: skip
           on_destination_older: replace
@@ -253,7 +255,7 @@ Source bundle digest mismatches fail validation before destination writes occur.
 
 ## Destination Fields
 
-Each destination embeds a backend config at the destination level and may also configure publishing, transforms, path mapping, links, and transfer behavior.
+Each destination embeds a backend config at the destination level and may also configure publishing, transforms, path mapping, links, reconciliation, and transfer behavior.
 
 ```yaml
 destinations:
@@ -265,6 +267,8 @@ destinations:
       html: false
     path_mapping:
       mode: preserve_relative
+    reconciliation:
+      mode: replace
     transfer:
       on_destination_same: skip
       on_destination_older: replace
@@ -278,7 +282,8 @@ destinations:
 - `transform`: required only when publishing generated HTML.
 - `path_mapping`: optional destination path mapping policy.
 - `links`: optional public URL metadata policy.
-- `transfer`: optional destination reconciliation policy.
+- `reconciliation`: optional managed-output reconciliation policy.
+- `transfer`: optional destination comparison action policy.
 
 Destination ids must be unique within a pipeline.
 
@@ -354,6 +359,41 @@ Primary URL policies:
 
 If no output matches the primary policy, per-output URLs may still be recorded and the top-level primary URL is omitted.
 
+## Reconciliation Policy
+
+```yaml
+reconciliation:
+  mode: replace
+```
+
+- `reconciliation.mode`: optional. Accepted values are `replace` and `merge`; default is `replace`.
+
+Reconciliation controls how a destination with older managed state is updated after transfer policy selects `replace_older`.
+
+`replace` deletes the prior managed outputs recorded in `.distributor.json`, deletes the state file, verifies the destination bundle path is empty, then writes only the newly planned outputs and a new state file. This is the default and is appropriate when each publication should exactly match the current publish and transform policy.
+
+`merge` keeps prior managed outputs that are not produced by the new plan. Planned paths already recorded in existing state may be overwritten; planned paths that already exist in storage but are not recorded as managed fail as unmanaged collisions. The resulting state file records the cumulative managed output set.
+
+Example merge destination:
+
+```yaml
+destinations:
+  - id: static-site
+    backend: local
+    path: /srv/reports/site
+    publish:
+      source: false
+      html: true
+    transform:
+      markdown_to_html:
+        enabled: true
+        mode: sidecar
+    reconciliation:
+      mode: merge
+```
+
+`links.primary_url` is selected from the newly planned outputs for the current run. Retained outputs keep their prior output metadata and timestamps.
+
 ## Transfer Policy
 
 ```yaml
@@ -408,6 +448,7 @@ Defaults are applied after YAML decoding and before validation:
 - `transform.markdown_to_html.mode: sidecar` when a Markdown transform block is present and mode is omitted
 - `path_mapping.mode: preserve_relative`
 - `links.primary: auto` when a `links` block is present and `primary` is omitted
+- `reconciliation.mode: replace`
 - `transfer.on_destination_same: skip`
 - `transfer.on_destination_older: replace`
 - `transfer.on_destination_newer: skip`
@@ -444,6 +485,7 @@ Local examples:
 - `local-index.yml`: local `index.html` publication.
 - `fan-out.yml`: local fan-out publication to source and HTML destinations.
 - `archive-and-latest.yml`: local archive plus fixed latest publication.
+- `merge-reconciliation.yml`: local HTML publication using merge reconciliation.
 - `http-upload-local.yml`: local HTTP upload server config; requires `DISTRIBUTOR_EXAMPLE_UPLOAD_TOKEN` in the process environment or as a secret-file name before running `serve`.
 
 Environment-gated remote examples: