Consolidate future work into docs/roadmap/future.md and remove completed roadmap docs

docs/cli.md

@@ -21,6 +21,8 @@ distributor [--help]
 distributor help
 distributor version [--format text|json]
 distributor run [--config <path>] [--dry-run] [--force] [--format text|json]
+distributor reconcile-state --config <path> --pipeline <id> --destination <id> [--all-owners] [--dry-run] [--format text|json]
+distributor prune --config <path> --pipeline <id> --destination <id> (--dry-run|--apply) [--format text|json]
 distributor serve [--config <path>]
 distributor validate [--format text|json] <path>
 distributor validate --config <path> --pipeline <id> [--bundle <path>] [--format text|json]
@@ -33,6 +35,8 @@ distributor manifest create --id <bundle-id> [options] <bundle-path>
 
 - `version` prints the application name and version.
 - `run` executes configured pipelines against their destinations.
+- `reconcile-state` repairs destination state records for missing managed outputs.
+- `prune` deletes managed outputs selected by the destination retention policy when `--apply` is supplied.
 - `serve` starts the authenticated HTTP upload API defined by the configuration file.
 - `validate` checks a local bundle path or a configured source bundle.
 - `inspect` reports manifest and file metadata for a local bundle path or a configured source bundle.
@@ -46,7 +50,7 @@ distributor manifest create --id <bundle-id> [options] <bundle-path>
 
 ### Common Output Format
 
-`--format text|json` is supported by `version`, `run`, `validate`, `inspect`, and `manifest create`.
+`--format text|json` is supported by `version`, `run`, `reconcile-state`, `prune`, `validate`, `inspect`, and `manifest create`.
 
 - `text` is the default human-readable output.
 - `json` emits one JSON document for successful command execution.
@@ -73,6 +77,36 @@ distributor run [--config <path>] [--dry-run] [--force] [--format text|json]
 
 `run` accepts no positional arguments.
 
+### `reconcile-state`
+
+```sh
+distributor reconcile-state --config <path> --pipeline <id> --destination <id> [--all-owners] [--dry-run] [--format text|json]
+```
+
+- `--config <path>` loads the pipeline configuration and is required.
+- `--pipeline <id>` selects the pipeline used to identify the destination root and is required.
+- `--destination <id>` selects the destination root and is required.
+- `--all-owners` repairs missing managed output records for every owner in a shared-root state file. Without it, shared-root repair is scoped to the selected pipeline and destination owner.
+- `--dry-run` reports repairs without rewriting `.distributor.json`.
+- `--format text|json` selects human-readable or machine-readable output.
+
+Without `--dry-run`, `reconcile-state` applies state repair by removing records for managed outputs that no longer exist in storage. It reports unmanaged entries but does not delete destination files, adopt unmanaged files, or validate output digests. The command accepts no positional arguments.
+
+### `prune`
+
+```sh
+distributor prune --config <path> --pipeline <id> --destination <id> (--dry-run|--apply) [--format text|json]
+```
+
+- `--config <path>` loads the pipeline configuration and is required.
+- `--pipeline <id>` selects the pipeline used to identify the destination root and owner scope.
+- `--destination <id>` selects the destination root and owner scope.
+- `--dry-run` reports planned managed-output deletes without deleting outputs or rewriting `.distributor.json`.
+- `--apply` deletes planned managed outputs and rewrites `.distributor.json` after confirmed deletes.
+- `--format text|json` selects human-readable or machine-readable output.
+
+Exactly one of `--dry-run` or `--apply` is required. The command uses only the selected destination's configured `retention.prune` policy; it does not accept one-off retention overrides. Apply mode deletes only planned managed output paths, preserves unmanaged files, and preserves `.distributor.json` even when no managed outputs remain.
+
 ### `serve`
 
 ```sh
@@ -174,6 +208,53 @@ go run ./cmd/distributor run --config examples/local-publish.yml
 
 Use `--format json` when automation needs structured run results. Use `--force` only when the operator has reviewed the destination state conflict and intentionally wants to continue.
 
+### Repair Destination State Records
+
+Preview missing managed output records for one configured destination:
+
+```sh
+go run ./cmd/distributor reconcile-state \
+  --config examples/local-publish.yml \
+  --pipeline example-source-bundle \
+  --destination local-archive \
+  --dry-run
+```
+
+Apply the repair after reviewing the report:
+
+```sh
+go run ./cmd/distributor reconcile-state \
+  --config examples/local-publish.yml \
+  --pipeline example-source-bundle \
+  --destination local-archive
+```
+
+Use `--all-owners` only for shared-root destination state when all owners inside the selected root should be repaired.
+
+### Prune Managed Outputs
+
+Preview managed outputs selected by the configured retention policy:
+
+```sh
+go run ./cmd/distributor prune \
+  --config examples/local-publish.yml \
+  --pipeline example-source-bundle \
+  --destination local-archive \
+  --dry-run
+```
+
+Apply after reviewing the report:
+
+```sh
+go run ./cmd/distributor prune \
+  --config examples/local-publish.yml \
+  --pipeline example-source-bundle \
+  --destination local-archive \
+  --apply
+```
+
+Use `--format json` when automation needs structured prune results.
+
 ### Run HTML And Fan-Out Examples
 
 ```sh
@@ -217,6 +298,8 @@ Text output is optimized for direct operator use. JSON output is optimized for a
 - Use `validate` before `run` when checking a bundle supplied by another process.
 - Use `inspect --format json` when automation needs manifest metadata, normalized file details, or checksum information.
 - Use `run --dry-run` before publishing to review destination actions.
+- Use `reconcile-state --dry-run` to inspect missing managed output records before repairing destination state.
+- Use `prune --dry-run` before `prune --apply` to review configured retention deletes.
 - Use [Configuration](config.md) for schema and default details.
 - Use [Troubleshooting](troubleshooting.md) for common errors and corrective action.
 - Use [Operations](operations.md) for HTTP upload operation, state files, and recovery workflows.

docs/config.md

@@ -17,7 +17,7 @@ YAML decoding rejects unknown fields. Defaults are applied after decoding and be
 Runtime backend support is command-specific:
 
 - `run`, `validate --config`, and `inspect --config` execute `local`, `ssh`, and `s3` sources.
-- `run` executes `local`, `ssh`, and `s3` destinations.
+- `run`, `reconcile-state`, and `prune` execute `local`, `ssh`, and `s3` destinations.
 - `serve` uses `http_upload` sources through the HTTP upload API and publishes to configured `local`, `ssh`, and `s3` destinations.
 - `http_upload` is valid only as a source backend.
 
@@ -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, state, reconciliation, retention, 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, state, reconciliation, retention, and transfer behavior.
 
 ```yaml
 destinations:
@@ -265,6 +267,10 @@ destinations:
       html: false
     path_mapping:
       mode: preserve_relative
+    state:
+      mode: single_owner
+    reconciliation:
+      mode: replace
     transfer:
       on_destination_same: skip
       on_destination_older: replace
@@ -278,7 +284,10 @@ 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.
+- `state`: optional destination state ownership policy.
+- `reconciliation`: optional managed-output reconciliation policy.
+- `retention`: optional managed-output retention policy.
+- `transfer`: optional destination comparison action policy.
 
 Destination ids must be unique within a pipeline.
 
@@ -354,6 +363,112 @@ 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.
 
+## Destination State Policy
+
+```yaml
+state:
+  mode: single_owner
+```
+
+- `state.mode`: optional. Accepted values are `single_owner` and `shared_root`; default is `single_owner`.
+
+`single_owner` state records one pipeline/destination owner for each destination bundle path and is the default state mode.
+
+`shared_root` records multiple pipeline/destination owners in one destination root. Publish execution preserves unrelated owners, rejects path ownership conflicts, and writes shared-root destination state.
+
+Use `shared_root` when multiple configured destinations intentionally write disjoint output paths into the same backend root:
+
+```yaml
+pipelines:
+  - id: reports-source
+    source:
+      backend: local
+      path: /var/spool/distributor/reports
+    destinations:
+      - id: shared-root
+        backend: local
+        path: /srv/reports/shared
+        state:
+          mode: shared_root
+        publish:
+          source: true
+          html: false
+  - id: reports-html
+    source:
+      backend: local
+      path: /var/spool/distributor/reports
+    destinations:
+      - id: shared-root
+        backend: local
+        path: /srv/reports/shared
+        state:
+          mode: shared_root
+        publish:
+          source: false
+          html: true
+        transform:
+          markdown_to_html:
+            enabled: true
+            mode: sidecar
+```
+
+Every output path in a shared root belongs to exactly one `pipeline_id` and `destination_id`. A different owner planning the same path fails as a conflict.
+
+## 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.
+
+## Retention Policy
+
+```yaml
+retention:
+  prune:
+    enabled: false
+    older_than: 168h
+    keep_latest: 3
+```
+
+- `retention.prune.enabled`: optional boolean. Default is `false`.
+- `retention.prune.older_than`: optional duration. When pruning is enabled, outputs older than this duration are eligible for pruning.
+- `retention.prune.keep_latest`: optional non-negative integer. When pruning is enabled, this many newest managed outputs are preserved before age-based pruning is considered.
+
+When `retention.prune.enabled` is `true`, at least one of `older_than` or `keep_latest` is required. `older_than` must be greater than zero, and `keep_latest` must be zero or greater.
+
+Pruning uses managed output `updated_at` timestamps from destination state. If both `keep_latest` and `older_than` are set, the newest `keep_latest` outputs are preserved first, then age-based pruning is applied to the remaining managed outputs.
+
+The `prune` command is owner-scoped for shared-root state. `prune --dry-run` reports selected managed outputs without writing. `prune --apply` deletes only selected managed output paths and rewrites destination state after confirmed deletes. It does not delete unmanaged files or `.distributor.json`, and it does not run automatically after `run`.
+
 ## Transfer Policy
 
 ```yaml
@@ -408,6 +523,9 @@ 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
+- `state.mode: single_owner`
+- `reconciliation.mode: replace`
+- `retention.prune.enabled: false`
 - `transfer.on_destination_same: skip`
 - `transfer.on_destination_older: replace`
 - `transfer.on_destination_newer: skip`
@@ -444,6 +562,8 @@ 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.
+- `shared-root.yml`: two local pipelines publishing disjoint outputs into one shared destination root.
 - `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:

docs/integrations/destination-state.md

@@ -4,17 +4,25 @@ Audience: operators, integrators, and maintainers who inspect or reason about de
 
 Each managed destination bundle path contains `.distributor.json`. This file is the destination sentinel and state record used for comparison, skip, replacement, and recovery decisions.
 
-## State Schema
+## Single-Owner State Schema
 
-Current schema version: `1`.
+State written by `run` for `state.mode: single_owner` uses schema version `2`.
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "distributor_version": "dev",
   "pipeline_id": "reports",
   "destination_id": "archive",
   "published_at": "2026-06-04T12:00:00Z",
+  "created_at": "2026-06-04T12:00:00Z",
+  "updated_at": "2026-06-04T12:00:00Z",
+  "state": {
+    "mode": "single_owner"
+  },
+  "reconciliation": {
+    "mode": "replace"
+  },
   "source": {
     "manifest": {
       "schema_version": 1,
@@ -37,7 +45,9 @@ Current schema version: `1`.
       "transform": "markdown_to_html",
       "url": "https://reports.example.com/archive/report.html",
       "sha256": "sha256:...",
-      "size": 2345
+      "size": 2345,
+      "created_at": "2026-06-04T12:00:00Z",
+      "updated_at": "2026-06-04T12:00:00Z"
     }
   ]
 }
@@ -45,10 +55,14 @@ Current schema version: `1`.
 
 Required fields:
 
-- `schema_version`: must be `1`.
+- `schema_version`: must be `2` for newly written state.
 - `pipeline_id`: configured pipeline id that wrote the state.
 - `destination_id`: configured destination id that wrote the state.
 - `published_at`: RFC3339 publication timestamp.
+- `created_at`: RFC3339 timestamp for when this destination state record was first created.
+- `updated_at`: RFC3339 timestamp for the latest state update.
+- `state.mode`: must be `single_owner`.
+- `reconciliation.mode`: `replace` or `merge`.
 - `source.manifest`: embedded source bundle manifest.
 - `outputs`: output records array; empty is allowed, but the field is required.
 
@@ -68,15 +82,31 @@ Each output record has:
 - `url`: optional absolute HTTP or HTTPS URL for the output.
 - `sha256`: lowercase `sha256:<64 hex>` digest of the output bytes.
 - `size`: output byte size, zero or greater.
+- `created_at`: RFC3339 timestamp for when this output path was first recorded as managed.
+- `updated_at`: RFC3339 timestamp for when this output path was last written or updated in state.
 
 Output paths must be unique and use clean relative slash-separated path rules.
 
+For replacement updates, newly planned outputs are written into state. For merge updates, retained output records preserve both timestamps, overwritten managed output records preserve `created_at` and receive a new `updated_at`, and new output records receive the current publication time for both fields.
+
+## Reconciliation Semantics
+
+Destination reconciliation applies when destination state is older than the source and transfer policy permits replacement.
+
+- `replace`: for single-owner state, delete managed output paths recorded in `outputs` plus `.distributor.json`, require the destination bundle path to be empty afterward, write the newly planned outputs, and write state whose `outputs` are exactly that new planned set. For shared-root state, delete only the current owner's omitted outputs and preserve unrelated owners.
+- `merge`: retain managed output paths omitted from the new plan, overwrite planned paths only when they are already recorded in existing state, fail when a newly planned path exists in storage but is not recorded as managed, and write state whose `outputs` are the cumulative managed set.
+
+Top-level `links.primary_url` is selected from the newly planned outputs for the current publication. Retained outputs keep their existing per-output URL metadata.
+
+If a merge publication fails after writing outputs, cleanup removes only newly created outputs from that failed attempt. Previously managed overwritten paths remain managed and are not removed by failed-attempt cleanup.
+
 ## Comparison Semantics
 
 `distributor` compares the current source manifest to destination state before writing:
 
 - No state and no content: publish new outputs.
 - No state and existing content: treat the destination as unmanaged.
+- Shared-root state without the current owner: publish new outputs for that owner if planned paths do not collide with other owners or unmanaged content.
 - Matching embedded source manifest: skip.
 - Same source id with older `created`: replace if policy allows.
 - Same source id with newer `created`: skip by default.
@@ -84,7 +114,131 @@ Output paths must be unique and use clean relative slash-separated path rules.
 - Different source id, pipeline id, or destination id: conflict.
 - Invalid state JSON or invalid state fields: conflict.
 
-Normal replacement deletes only managed output paths recorded in `outputs` plus `.distributor.json`. Forced replacement deletes the bounded destination bundle path.
+Normal single-owner replacement deletes only managed output paths recorded in `outputs` plus `.distributor.json`. Shared-root replacement deletes only omitted outputs for the current owner. Merge publication retains omitted managed outputs. Forced replacement deletes the bounded destination bundle path.
+
+## State Repair Semantics
+
+`distributor reconcile-state` can remove managed output records for files that no longer exist in destination storage. It uses the configured pipeline and destination selector to open one destination root and reads that root's `.distributor.json`.
+
+For single-owner state, the state `pipeline_id` and `destination_id` must match the selected pipeline and destination. The command checks output paths recorded in `outputs`, reports missing managed outputs, reports unmanaged entries under the destination root, and removes missing output records from valid state unless `--dry-run` is set.
+
+For shared-root state, repair is scoped to the selected owner by default. With `--all-owners`, it checks and repairs missing output records for every owner in the selected shared-root state file.
+
+State repair does not validate output digests, delete destination files, adopt unmanaged entries, or rewrite invalid or mismatched state.
+
+## Prune Semantics
+
+`distributor prune` can delete managed outputs selected by the configured destination retention policy. It uses the configured pipeline and destination selector to open one destination root and reads that root's `.distributor.json`.
+
+For single-owner state, the state `pipeline_id` and `destination_id` must match the selected pipeline and destination. For shared-root state, pruning is scoped to the selected owner and preserves other owners.
+
+Prune planning uses output `updated_at` timestamps. `prune --dry-run` reports planned managed-output deletes without deleting files or rewriting state. `prune --apply` deletes only planned managed output paths, removes confirmed deleted records from valid state, and updates the state timestamp. It does not delete unmanaged files or `.distributor.json`.
+
+## Compatibility
+
+`distributor` can read schema version `1` destination state for compatibility. When v1 state is read, it is treated as single-owner state with `reconciliation.mode: replace`. Missing top-level `created_at` and `updated_at` are inferred from `published_at`, and missing per-output timestamps are also inferred from `published_at`.
+
+Newly written single-owner destination state from publish execution uses schema version `2`.
+
+## Shared-Root State Schema
+
+State written by `run` for `state.mode: shared_root` uses schema version `3`.
+
+```json
+{
+  "schema_version": 3,
+  "distributor_version": "dev",
+  "created_at": "2026-06-04T12:00:00Z",
+  "updated_at": "2026-06-04T12:10:00Z",
+  "state": {
+    "mode": "shared_root"
+  },
+  "owners": [
+    {
+      "pipeline_id": "reports",
+      "destination_id": "archive",
+      "reconciliation": {
+        "mode": "merge"
+      },
+      "source": {
+        "manifest": {
+          "schema_version": 1,
+          "id": "reports.example.2026-06-04",
+          "digest": "sha256:...",
+          "created": "2026-06-04T11:55:00Z",
+          "files": [
+            {"path": "report.md", "sha256": "sha256:...", "size": 1234}
+          ]
+        }
+      },
+      "links": {
+        "primary_url": "https://reports.example.com/archive/report.html"
+      }
+    }
+  ],
+  "outputs": [
+    {
+      "path": "report.html",
+      "kind": "generated",
+      "source_path": "report.md",
+      "transform": "markdown_to_html",
+      "url": "https://reports.example.com/archive/report.html",
+      "sha256": "sha256:...",
+      "size": 2345,
+      "pipeline_id": "reports",
+      "destination_id": "archive",
+      "source_id": "reports.example.2026-06-04",
+      "source_digest": "sha256:...",
+      "source_created": "2026-06-04T11:55:00Z",
+      "created_at": "2026-06-04T12:00:00Z",
+      "updated_at": "2026-06-04T12:10:00Z"
+    }
+  ]
+}
+```
+
+Shared-root required fields:
+
+- `schema_version`: must be `3`.
+- `created_at`: RFC3339 timestamp for when this shared-root state record was first created.
+- `updated_at`: RFC3339 timestamp for the latest shared-root state update.
+- `state.mode`: must be `shared_root`.
+- `owners`: owner records keyed by `pipeline_id` and `destination_id`; each owner records its latest source manifest and reconciliation mode.
+- `outputs`: output records for every managed path under the shared destination root.
+
+Shared-root optional fields:
+
+- `distributor_version`: application version string when available.
+- `owners[].links.primary_url`: absolute HTTP or HTTPS URL selected by that owner's destination link policy.
+
+Shared-root output records carry the same `path`, `kind`, `source_path`, `transform`, `url`, `sha256`, `size`, `created_at`, and `updated_at` fields as single-owner outputs. They also include the owner `pipeline_id` and `destination_id`, plus compact source identity fields `source_id`, `source_digest`, and `source_created`.
+
+## Shared-Root Ownership
+
+Shared-root state is owner-scoped by `pipeline_id` and `destination_id`.
+
+- One output path may be owned by only one owner.
+- The same owner may overwrite its own managed paths.
+- A different owner planning an already owned path fails as a conflict.
+- A planned path that exists in storage but is not recorded in state fails as unmanaged content unless forced replacement is explicitly selected.
+
+When an owner publishes, unrelated owner records and output records are preserved. The publishing owner's record is updated with the latest source manifest, reconciliation mode, and latest primary URL when present.
+
+## Shared-Root Timestamps
+
+For shared-root state:
+
+- top-level `created_at` remains the original shared-root state creation time;
+- top-level `updated_at` changes after a successful state write;
+- output `created_at` remains stable for an existing managed path;
+- output `updated_at` changes only when that path is rewritten;
+- newly managed output paths receive the publication time for both output timestamps.
+
+## Shared-Root Migration
+
+If `state.mode: shared_root` is configured and existing state is a compatible single-owner `.distributor.json` for the same pipeline id and destination id, the next successful publish writes schema version `3` shared-root state for that owner.
+
+If existing single-owner state belongs to a different pipeline or destination, publish fails as a conflict. `distributor` does not implicitly take over unrelated state or unmanaged files.
 
 ## Boundaries
 

docs/integrations/s3.md

@@ -52,7 +52,7 @@ The adapter uses these S3 operations:
 
 Writes buffer the input and set `ContentLength`. If no content type is supplied by the caller, the adapter infers a content type from the logical path.
 
-Normal replacement and failed-write cleanup delete only managed output objects plus `.distributor.json`. Forced replacement deletes objects under the bounded destination bundle prefix. The backend does not manage bucket versioning, lifecycle rules, object lock, or delete markers.
+Normal replacement and failed-write cleanup delete only managed output objects plus `.distributor.json`. Merge publication retains omitted managed objects and may overwrite existing managed objects. Forced replacement deletes objects under the bounded destination bundle prefix. The backend does not manage bucket versioning, lifecycle rules, object lock, or delete markers.
 
 ## Error Mapping
 

docs/integrations/ssh-sftp.md

@@ -54,7 +54,7 @@ The configured `path` is the backend root. All source discovery, destination pat
 
 The adapter rejects symlink ancestors for reads and writes. Reads require regular files. Writes create parent directories and prefer atomic temp-file-plus-rename writes when requested. Walk output is sorted through the shared storage walker.
 
-Managed cleanup and normal replacement delete only managed output paths plus `.distributor.json`. Forced replacement deletes the bounded destination bundle path.
+Managed cleanup and normal replacement delete only managed output paths plus `.distributor.json`. Merge publication retains omitted managed paths and may overwrite existing managed paths. Forced replacement deletes the bounded destination bundle path.
 
 ## Boundaries
 

docs/internal/app.md

@@ -4,23 +4,23 @@ Audience: developers and LLM coding agents changing `internal/app`.
 
 ## Purpose
 
-`internal/app` owns top-level application use cases: run, single-pipeline run, staged-source run, validate, inspect, manifest creation, and HTTP upload serving. It coordinates config loading, secret resolution, backend construction, source discovery, destination selection, publish planning/execution, notification handoff, output projection, and upload coordination.
+`internal/app` owns top-level application use cases: run, single-pipeline run, staged-source run, validate, inspect, manifest creation, reconcile-state planning/repair, prune planning/execution, and HTTP upload serving. It coordinates config loading, secret resolution, backend construction, source discovery, destination selection, publish planning/execution, state repair reporting, retention prune reporting, notification handoff, output projection, and upload coordination.
 
 ## Inputs And Outputs
 
 Inputs include app option structs, contexts, config paths, pipeline ids, local source roots, dry-run/force flags, output format, stdout writers, HTTP requests, and optional notifier implementations.
 
-Outputs include `RunReport`, validate/inspect/manifest results, CLI text/JSON projections, HTTP upload responses, upload status records, and errors. Destination-scoped failures can return a partial run report plus an aggregated error; fatal setup failures return before a complete report exists.
+Outputs include `RunReport`, `ReconcileStateReport`, `PrunePlanReport`, `PruneReport`, validate/inspect/manifest results, CLI text/JSON projections, HTTP upload responses, upload status records, and errors. Destination-scoped failures can return a partial run report plus an aggregated error; fatal setup failures return before a complete report exists.
 
 ## Boundaries
 
 `internal/app` wires packages together but does not own manifest validation rules, destination state comparison, storage path rules, publish safety policy, transform rendering, config schema validation, or backend protocol behavior.
 
-User-facing command parsing stays in `internal/cli`. User-facing config reference stays in `docs/config.md`. External contracts live under `docs/integrations/`.
+User-facing command parsing stays in `internal/cli`, including `reconcile-state` and `prune` flag validation and help text. User-facing config reference stays in `docs/config.md`. External contracts live under `docs/integrations/`.
 
 ## Config Fields Used
 
-The package consumes the loaded `config.Config`: `server.http`, `secrets.directory`, pipeline ids, source and destination backend fields, validation policy, publish policy, transform policy, path mapping, links, and transfer policy.
+The package consumes the loaded `config.Config`: `server.http`, `secrets.directory`, pipeline ids, source and destination backend fields, validation policy, publish policy, transform policy, path mapping, links, state policy, reconciliation policy, retention policy, and transfer policy.
 
 Config fields are validated and defaulted by `internal/config` before app workflows use them.
 
@@ -34,13 +34,19 @@ The app layer registers default transforms, including Markdown-to-HTML, and supp
 
 Run workflows discover and validate source bundles through `internal/bundle`. Destination state actions are prepared and written through `internal/publish` and `internal/state`; the app layer records report projections of those actions and results.
 
+Reconcile-state workflows load one configured pipeline/destination selector, open that destination root, parse the root `.distributor.json`, and report missing managed output records plus unmanaged storage entries. Managed output existence checks use storage `Stat`; unmanaged reporting uses bounded storage `Walk` and excludes `.distributor.json` plus all paths already recorded as managed. Apply mode removes missing managed output records from state and rewrites valid state only; dry-run reports the same repair without writing. Text output reports `changed`, `would_change`, or `unchanged`; JSON output uses the shared app envelope. It does not validate output digests, delete destination files, adopt unmanaged files, or rewrite invalid or mismatched state.
+
+Prune planning consumes a parsed destination state document and a validated retention prune policy, then returns owner-scoped managed output records that would be pruned or preserved. Planning uses output `updated_at` timestamps, applies `keep_latest` before `older_than` when both are configured, and does not open storage, delete files, or rewrite state.
+
+Prune execution loads one configured pipeline/destination selector, opens that destination root, parses the root `.distributor.json`, and builds a plan from the destination retention policy. Dry-run returns the same planned and preserved managed output records without deleting files or rewriting state. Apply mode deletes only planned managed output paths, never unmanaged files or `.distributor.json`, then removes confirmed deleted records from state and updates the state timestamp. If a delete fails after earlier deletes succeeded, it rewrites state only for the confirmed deletions and preserves records for the failed and unattempted outputs so a retry remains accurate. Text output reports `changed`, `would_change`, or `unchanged`; JSON output uses the shared app envelope.
+
 HTTP uploads stage and validate archives before enqueueing a pipeline run with a local staged source root. Go producers can use the public `pkg/upload` package to create client-side gzip tar uploads for this server contract; `internal/app` remains the server-side orchestration boundary and does not import that producer package.
 
 Upload idempotency is owned by the upload coordinator. Optional `Idempotency-Key` values are scoped to token id, pipeline id, and key. The coordinator reserves a key while staging is in progress, records the accepted run id with the validated source manifest identity after staging succeeds, returns the original accepted record for the same scoped key and same manifest, and rejects the same scoped key with a different manifest as a conflict.
 
 ## Skip And Resume Behavior
 
-Fan-out destinations are independent. A destination failure is recorded and does not prevent later destinations from being attempted. Dry-run builds plans and reports without destination writes, destination state writes, notifier calls, or SSH known-host persistence.
+Fan-out destinations are independent. A destination failure is recorded and does not prevent later destinations from being attempted. Run dry-run builds plans and reports without destination writes, destination state writes, notifier calls, or SSH known-host persistence. Reconcile-state dry-run reports missing managed records and unmanaged entries without rewriting state. Prune dry-run reports planned managed output deletes without deleting outputs or rewriting state.
 
 HTTP upload status is in memory. Accepted jobs move through accepted, queued, running, succeeded, or failed states and expire after configured retention. Upload idempotency records are also memory-only, expire with the completed status record for their accepted run, and are cleared by process restart.
 
@@ -48,11 +54,18 @@ HTTP upload status is in memory. Accepted jobs move through accepted, queued, ru
 
 Runtime setup fails for config load, config validation, secret loading, or credential resolution errors. Source setup failures stop the affected run before destination planning. Destination open, planning, execution, and notification failures are recorded as destination failures where a partial result exists.
 
+Reconcile-state setup fails unless the caller supplies a pipeline id and destination id that select one configured destination root. Single-owner state must match that pipeline/destination owner. Shared-root all-owner repair still uses the selected destination to identify the root, then applies repair across owners inside that root. Invalid, unreadable, or ambiguous state fails before any rewrite.
+
+Prune setup fails unless the caller supplies a pipeline id and destination id that select one configured destination root. Single-owner state must match that pipeline/destination owner. Shared-root pruning is scoped to the selected owner and preserves unrelated owners. Invalid, unreadable, or ambiguous state fails before deletes or rewrites. Delete failures return a report with confirmed deletions and the failed output.
+
 HTTP upload startup fails if upload tokens are missing, empty, or duplicated. Upload requests can fail during authentication, idempotency-key validation, content-type validation, idempotency conflict checks, queue admission, archive staging, source validation, or later publish execution.
 
 ## Tests To Inspect
 
 - `internal/app/*_test.go`
+- `internal/app/prune_test.go`
+- `internal/cli/reconcile_state_test.go`
+- `internal/cli/prune_test.go`
 - `internal/cli/root_test.go`
 - `internal/config/*_test.go`
 - `internal/ingest/*_test.go`
@@ -67,3 +80,5 @@ HTTP upload startup fails if upload tokens are missing, empty, or duplicated. Up
 - Upload admission stages and validates a bundle before returning a run id.
 - Idempotent upload retries compare normalized source manifest identity, not archive bytes.
 - Runtime backend registration remains app-owned.
+- Reconcile-state repairs state records only; it never deletes or adopts destination files.
+- Prune execution deletes managed output paths only and preserves failed records for retry.

docs/internal/config.md

@@ -18,7 +18,7 @@ The canonical user-facing config reference is `docs/config.md`.
 
 ## Config Fields Used
 
-The package defines all user-visible config fields: `server.http`, `secrets`, `pipelines`, source and destination backend fields, validation policy, publish policy, transform policy, path mapping, links, and transfer policy.
+The package defines all user-visible config fields: `server.http`, `secrets`, `pipelines`, source and destination backend fields, validation policy, publish policy, transform policy, path mapping, links, state policy, reconciliation policy, retention policy, and transfer policy.
 
 ## Adapters Used
 
@@ -26,7 +26,7 @@ No external storage adapters are used directly. The package exposes normalized c
 
 ## State And Manifest Behavior
 
-The package does not parse source manifests or destination state. It validates config values that later affect manifest validation and destination state, such as publish/transform combinations, links, transfer policy, backend roots, S3 prefix shape, and HTTP upload source settings.
+The package does not parse source manifests or destination state. It validates config values that later affect manifest validation and destination state, such as publish/transform combinations, links, state policy, reconciliation policy, retention policy, transfer policy, backend roots, S3 prefix shape, and HTTP upload source settings.
 
 ## Skip And Resume Behavior
 

docs/internal/publish.md

@@ -8,19 +8,19 @@ Audience: developers and LLM coding agents changing `internal/publish`.
 
 ## Inputs And Outputs
 
-Inputs are a source bundle, source backend, destination backend, pipeline id, destination id, destination bundle path, path mapping mode, publish policy, transform policy, optional link policy, transformer resolver, transfer policy, distributor version, and force flag.
+Inputs are a source bundle, source backend, destination backend, pipeline id, destination id, destination bundle path, path mapping mode, publish policy, transform policy, optional link policy, state policy, reconciliation policy, transformer resolver, transfer policy, distributor version, and force flag.
 
-Output from planning is a `Plan` with action, reason, destination identity, selected outputs, optional existing state, optional primary URL, and force metadata. Execution writes selected source outputs, generated outputs, and `.distributor.json` for executable publish or replacement actions.
+Output from planning is a `Plan` with action, reason, destination identity, selected outputs, state mode, owner scope, reconciliation mode, optional existing single-owner or shared-root state, optional primary URL, and force metadata. Shared-root plans also expose other-owner outputs to preserve, current-owner outputs retained by merge, current-owner outputs deleted by replace, and current-owner outputs to write. Execution writes selected source outputs, generated outputs, and `.distributor.json` for executable publish or replacement actions.
 
 ## Boundaries
 
-The package does not parse CLI flags, load config files, open concrete adapters, discover source bundles, select fixed-path bundle candidates, register transforms, or render command output. The app layer supplies validated request data and concrete dependencies.
+The package does not parse CLI flags, load config files, open concrete adapters, discover source bundles, select fixed-path bundle candidates, register transforms, prune retained outputs, or render command output. The app layer supplies validated request data and concrete dependencies.
 
 External destination state semantics are documented in `docs/integrations/destination-state.md`.
 
 ## Config Fields Used
 
-The package consumes already-defaulted config values for destination `publish`, `transform`, `links`, `transfer`, and path mapping mode. It uses `config.ValidatePublishTransformPolicy` for publish/transform consistency.
+The package consumes already-defaulted config values for destination `publish`, `transform`, `links`, `state`, `reconciliation`, `transfer`, and path mapping mode. It uses `config.ValidatePublishTransformPolicy` for publish/transform consistency.
 
 ## Adapters Used
 
@@ -30,19 +30,25 @@ The package depends on `internal/storage.Backend` for source and destination IO,
 
 Planning inspects destination state through `internal/state`, compares it with the source manifest, and maps comparison outcomes plus transfer policy into actions: `publish_new`, `replace_older`, `force_replace`, `skip_same`, `skip_destination_newer`, `fail_conflict`, or `fail_unmanaged`.
 
-Execution writes destination state after selected outputs are written. Destination state includes copied source output metadata, generated output metadata, embedded source manifest, link metadata when configured, pipeline id, destination id, and publication timestamp.
+Single-owner destinations compare the whole destination state against the configured pipeline and destination ids. Shared-root destinations compare only the current owner scope, keyed by pipeline id and destination id. An absent shared-root owner is publishable for that owner unless a planned output collides with unmanaged storage content. Planned writes to a path owned by another shared-root owner fail as conflicts.
+
+Execution writes destination state after selected outputs are written. Destination state includes copied source output metadata, generated output metadata, output timestamps, embedded source manifest, reconciliation metadata, link metadata when configured, pipeline id, destination id, and publication timestamps.
 
 ## Skip And Resume Behavior
 
-`skip_same` and `skip_destination_newer` execute as no-ops. Normal replacement removes only managed output paths from existing state plus `.distributor.json`; this allows retries without broad deletion. Failed writes trigger cleanup of outputs written during that failed attempt where practical.
+`skip_same` and `skip_destination_newer` execute as no-ops. Replacement-mode single-owner updates remove managed output paths from existing state plus `.distributor.json`, verify the destination is empty, and write state whose outputs are exactly the new plan. Replacement-mode shared-root updates remove only current-owner omitted outputs and preserve unrelated owners. Merge-mode updates retain omitted managed outputs, overwrite only paths already recorded as managed, reject unmanaged destination path collisions, and write cumulative output state. Failed writes trigger cleanup where practical; merge cleanup removes only newly created outputs from the failed attempt.
+
+Shared-root execution writes schema version `3` state. It preserves unrelated owner records and outputs, updates only the publishing owner metadata, preserves root `created_at`, and updates root `updated_at` after successful state writes. Compatible single-owner state for the same pipeline and destination is converted to shared-root state on successful publish.
 
 Forced replacement is explicit per request and deletes the bounded destination bundle path before writing new outputs and state.
 
+Retention pruning is not part of publish execution and does not run automatically after a successful publish. The app-level prune workflow uses destination state after publication to select managed outputs for deletion.
+
 ## Failure Behavior
 
-Planning fails for incomplete requests, invalid publish/transform policy, output path collisions, invalid destination state, unmanaged destination content without force, conflict outcomes not allowed by transfer policy, unresolved transforms, invalid Markdown output selection, and invalid link URL planning.
+Planning fails for incomplete requests, invalid publish/transform policy, invalid state mode, invalid reconciliation mode, output path collisions, invalid destination state, unmanaged destination content without force, shared-root owner path conflicts, conflict outcomes not allowed by transfer policy, unresolved transforms, invalid Markdown output selection, and invalid link URL planning.
 
-Execution fails on delete, read, transform output, write, state validation, state serialization, or context errors. Execution refuses actions that are not executable publish or replacement actions.
+Execution fails on delete, read, transform output, unmanaged merge path collision, shared-root ownership conflict, write, state validation, state serialization, or context errors. Execution refuses actions that are not executable publish or replacement actions.
 
 ## Tests To Inspect
 
@@ -56,7 +62,11 @@ Execution fails on delete, read, transform output, write, state validation, stat
 - Planning is deterministic for the same request and destination state.
 - Destination bundle paths are caller-supplied and backend-root-relative.
 - URL generation uses URL path semantics and never infers public URLs from backend config.
-- Normal replacement deletes only managed paths recorded in existing state plus `.distributor.json`.
+- Replacement reconciliation deletes only managed paths recorded in existing state plus `.distributor.json` for single-owner state, and only current-owner omitted outputs for shared-root state.
+- Merge reconciliation never adopts unmanaged content.
+- Merge state output records are cumulative for the single owner.
+- Shared-root planning is owner-scoped and preserves unrelated owner outputs.
+- Shared-root execution writes owner-scoped changes without deleting unrelated owners.
 - Forced replacement deletes only within the supplied destination bundle path.
 - Destination state is written after selected outputs are written.
 - Transform resolution stays behind a caller-supplied interface.

docs/internal/state.md

@@ -18,7 +18,7 @@ The external destination state contract is documented in `docs/integrations/dest
 
 ## Config Fields Used
 
-None directly. Destination ids, pipeline ids, and link URLs originate from config but are supplied as values by callers.
+`internal/state` uses config state mode and reconciliation mode constants for destination state validation and legacy state normalization. Destination ids, pipeline ids, and link URLs originate from config but are supplied as values by callers.
 
 ## Adapters Used
 
@@ -26,22 +26,44 @@ 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.
+`.distributor.json` schema version is `2` for newly written single-owner state. Required fields are `pipeline_id`, `destination_id`, `published_at`, `created_at`, `updated_at`, `state.mode`, `reconciliation.mode`, `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.
+Schema version `1` state remains readable. Parsing infers `state.mode: single_owner`, `reconciliation.mode: replace`, top-level `created_at` and `updated_at` from `published_at`, and per-output timestamps from `published_at`.
+
+Schema version `3` is shared-root state. It records `state.mode: shared_root`, shared state timestamps, owner records keyed by pipeline id and destination id, each owner's latest source manifest and reconciliation metadata, optional owner primary links, and output records for every managed path. Shared-root output records include owner ids and compact source identity fields for source id, digest, and creation time.
+
+Shared-root publish conversion is explicit. Compatible single-owner state for the same pipeline and destination can be projected into the current owner scope by publish execution. Unrelated single-owner state remains a conflict.
+
+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, created and updated timestamps, and transform ids for generated outputs. Stored URLs must pass `internal/link` validation.
+
+The package also provides helpers for finding output records by path, projecting planned publish outputs into timestamped state outputs, merging retained and newly planned output records, computing managed output paths from single-owner state, removing missing managed output records from single-owner state, and building prune candidates from managed outputs.
+
+For shared-root state, helpers parse either state shape, identify the current owner scope, return an owner's latest source manifest, list managed paths for one owner or all owners, detect path ownership conflicts, project planned owner outputs, merge one owner's planned outputs while preserving unrelated owners, replace one owner's outputs by removing that owner's omitted outputs, remove missing managed output records for either the current owner or every owner, and build owner-scoped prune candidates.
+
+Shared-root helper projections preserve output `created_at` for existing managed paths and use the current publication time for rewritten `updated_at`. Root-level `created_at` preservation is owned by publish execution.
 
 ## 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.
 
+Shared-root comparison is owner-scoped. It compares only the owner keyed by the current pipeline id and destination id, treats an absent owner as absent destination state for that owner, and can compare compatible single-owner state for the current owner without converting unrelated single-owner state.
+
+Missing-output removal helpers are pure state transformations used by app-level state repair. They remove matching output records only and leave storage inspection, timestamp updates, validation, and state rewrites to callers.
+
+Prune planning helpers are pure. They select managed output candidates, sort deterministically by `updated_at` and path, preserve the newest `keep_latest` candidates before evaluating `older_than`, and return planned prune/preserve lists without mutating state. App-level prune execution and the `prune` command use the missing-output removal helpers to remove only confirmed deleted records after storage deletion succeeds.
+
 ## 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.
+Parsing rejects invalid JSON, trailing data, missing required fields, invalid timestamps, invalid state mode, invalid reconciliation mode, invalid embedded manifests, duplicate owners, duplicate outputs, invalid output paths, unsupported output kinds, missing generated transforms, invalid URLs, invalid digests, negative sizes, and shared-root outputs whose owner is not registered.
 
 ## Tests To Inspect
 
 - `internal/state/distributor_test.go`
+- `internal/state/shared_root_test.go`
+- `internal/state/prune_test.go`
 - `internal/state/compare_test.go`
+- `internal/app/reconcile_state_test.go`
+- `internal/cli/reconcile_state_test.go`
 - `internal/publish/*_test.go`
 
 ## Architectural Invariants
@@ -49,6 +71,13 @@ Parsing rejects invalid JSON, trailing data, missing required fields, invalid ti
 - `.distributor.json` is the destination sentinel and state record.
 - Comparison does not mutate storage.
 - Embedded source manifests use the source bundle contract.
+- Newly written single-owner state uses schema version `2`.
+- Schema version `1` state remains readable as replacement-mode single-owner state.
+- Schema version `3` shared-root state is parsed and validated without converting unrelated single-owner state.
+- Shared-root owner updates preserve unrelated owners and reject planned path collisions with other owners.
+- Missing-output repair helpers preserve unrelated owner records and outputs.
+- Prune planning uses output `updated_at` and preserves unrelated shared-root owners.
 - Generated outputs always record a transform id.
+- Output records always carry created and updated timestamps after parsing.
 - Stored URLs are optional and must be absolute HTTP or HTTPS URLs when present.
 - `distributor_version` is diagnostic metadata, not a comparison key.

docs/internal/storage.md

@@ -26,13 +26,15 @@ Local, SSH/SFTP, and S3-compatible adapters implement `storage.Backend`. `intern
 
 ## State And Manifest Behavior
 
-Storage owns `.distributor.json` path helpers through `StateFileName`, `StatePath`, and `ManagedBundleTargets`. It does not parse source manifests or destination state.
+Storage owns `.distributor.json` path helpers through `StateFileName`, `StatePath`, `ManagedOutputTargets`, and `ManagedBundleTargets`. It does not parse source manifests or destination state.
 
 Logical paths are slash-separated and relative to a backend root. Prefix validation allows an empty prefix to mean the backend root; file path validation requires a non-empty path.
 
+Reconcile-state callers use `Stat` to check whether managed output paths still exist and bounded recursive `Walk` to report unmanaged entries under a selected destination root. Prune execution callers use `DeleteManagedOutputs` for selected managed output records so `.distributor.json` is not part of the deletion target set. Storage does not decide whether entries are managed; callers compare entries against destination state.
+
 ## Skip And Resume Behavior
 
-Storage has no publication skip policy. It supplies `HasAny` for unmanaged-content checks, `DeleteManagedBundle` target construction for normal replacement cleanup, and `DeletePrefix` semantics for explicit forced replacement.
+Storage has no publication skip policy. It supplies `HasAny` for unmanaged-content checks, `Stat` and `Walk` for state repair inspection, `DeleteManagedOutputs` target construction for managed output cleanup, `DeleteManagedBundle` target construction for normal replacement cleanup, and `DeletePrefix` semantics for explicit forced replacement.
 
 ## Failure Behavior
 
@@ -42,6 +44,7 @@ Storage errors use typed categories: not found, already exists, not empty, inval
 
 - `internal/storage/*_test.go`
 - `internal/storage/fake/*_test.go`
+- `internal/app/reconcile_state_test.go`
 - `internal/adapters/local/*_test.go`
 - `internal/adapters/ssh/*_test.go`
 - `internal/adapters/s3/*_test.go`
@@ -51,6 +54,6 @@ Storage errors use typed categories: not found, already exists, not empty, inval
 - Logical paths are clean relative slash-separated paths confined to the backend root.
 - Core packages never import concrete adapters.
 - `storage.List` returns deterministic sorted entries.
-- Managed deletion targets are recorded outputs plus `.distributor.json`.
+- Managed output deletion targets are recorded outputs only; managed bundle deletion targets are recorded outputs plus `.distributor.json`.
 - Prefix deletion is bounded to the requested logical prefix.
 - Runtime registration remains app-owned.

docs/operations.md

@@ -56,7 +56,7 @@ Destination path mapping controls where each source bundle is published beneath
 
 Fixed destinations select the newest discovered source bundle by manifest `created` timestamp. If multiple bundles have the same timestamp, the source-root-relative bundle path in ascending order wins.
 
-Published destination bundle paths contain `.distributor.json`. See [Destination State Contract](integrations/destination-state.md). This file is both the managed sentinel and the destination state record. It records the pipeline id, destination id, publication time, source manifest, copied outputs, generated outputs, and optional public URL metadata.
+Published destination bundle paths contain `.distributor.json`. See [Destination State Contract](integrations/destination-state.md). This file is both the managed sentinel and the destination state record. It records the pipeline id, destination id, publication time, state mode, reconciliation mode, source manifest, copied outputs, generated outputs, output timestamps, and optional public URL metadata.
 
 `manifest.json` from the source bundle is not copied as destination state.
 
@@ -71,19 +71,90 @@ Published destination bundle paths contain `.distributor.json`. See [Destination
 - Invalid destination state, identity mismatch, different source id, or same-created digest mismatch: fail by default.
 - Content without `.distributor.json`: fail as unmanaged content by default.
 
-Normal replacement deletes only managed output paths recorded in `.distributor.json` plus the state file, then verifies the destination bundle path is empty before writing new outputs and state.
+When destination state is older than the source, `transfer.on_destination_older` controls whether publication may proceed and `reconciliation.mode` controls how managed outputs are updated.
 
-If a write fails after some outputs were written, `distributor` attempts to delete outputs from that failed attempt so a retry does not treat partial outputs as unmanaged content. Operators should still inspect the destination after a failed write before retrying.
+`reconciliation.mode: replace` is the default. It deletes only managed output paths recorded in `.distributor.json` plus the state file, verifies the destination bundle path is empty, then writes the newly planned outputs and state. The new state `outputs` array is exactly the newly planned output set.
+
+`reconciliation.mode: merge` retains prior managed outputs that are omitted from the new plan. It overwrites planned paths only when those paths are already recorded in existing state as managed. If a newly planned path already exists in storage but is not recorded in state, publication fails as an unmanaged path collision. The new state `outputs` array is the cumulative managed output set.
+
+For both modes, retained or overwritten paths are identified only from `.distributor.json`; unmanaged files are not adopted.
+
+For `state.mode: shared_root`, one destination root may contain outputs from multiple pipeline/destination owners. Comparisons, replacement, and merge retention are scoped to the current owner. Outputs owned by other owners are preserved. A planned output path owned by another owner fails as a conflict, and a planned path that exists in storage but is not recorded in state fails as unmanaged content by default.
+
+If `state.mode: shared_root` is configured on a destination whose existing single-owner state belongs to the same pipeline and destination, the next successful publish converts that state file to shared-root schema. Existing single-owner state for a different pipeline or destination remains a conflict.
+
+If a write fails after some outputs were written, `distributor` attempts cleanup before returning the error. In `replace` mode, cleanup removes outputs written during that failed attempt. In `merge` mode, cleanup removes only newly created outputs from that failed attempt; overwritten managed outputs are left in place because they previously belonged to the managed set. Operators should still inspect the destination after a failed write before retrying.
 
 Fan-out destinations are independent. If one destination fails after planning or execution begins, later destinations are still attempted. The command exits non-zero if any destination failed.
 
+## Destination State Repair
+
+Use `reconcile-state` when `.distributor.json` still records managed outputs that no longer exist in destination storage. This repairs the state record only; it does not restore missing files.
+
+Preview the repair first:
+
+```sh
+go run ./cmd/distributor reconcile-state \
+  --config <config-path> \
+  --pipeline <pipeline-id> \
+  --destination <destination-id> \
+  --dry-run
+```
+
+Apply after reviewing the report:
+
+```sh
+go run ./cmd/distributor reconcile-state \
+  --config <config-path> \
+  --pipeline <pipeline-id> \
+  --destination <destination-id>
+```
+
+The command opens the configured destination root selected by `--pipeline` and `--destination`, reads the root `.distributor.json`, checks each managed output path with storage metadata, reports missing managed outputs, and reports unmanaged entries under that root. It excludes `.distributor.json` and already managed paths from unmanaged reporting.
+
+Without `--dry-run`, it removes missing managed output records from valid state and rewrites `.distributor.json`. It never deletes destination files, adopts unmanaged files, validates output digests, or rewrites invalid or mismatched state.
+
+For single-owner state, the state owner must match the selected pipeline and destination. For shared-root state, repair is scoped to the selected owner by default. Add `--all-owners` only when every owner in the selected shared-root state should have missing managed output records removed.
+
+## Managed Output Pruning
+
+Use `prune` when a destination config has `retention.prune.enabled: true` and old managed outputs should be removed according to that configured policy. Pruning is never automatic after publish.
+
+Preview selected managed outputs first:
+
+```sh
+go run ./cmd/distributor prune \
+  --config <config-path> \
+  --pipeline <pipeline-id> \
+  --destination <destination-id> \
+  --dry-run
+```
+
+Apply after reviewing the report:
+
+```sh
+go run ./cmd/distributor prune \
+  --config <config-path> \
+  --pipeline <pipeline-id> \
+  --destination <destination-id> \
+  --apply
+```
+
+The command opens the configured destination root selected by `--pipeline` and `--destination`, reads the root `.distributor.json`, and plans from the selected destination's `retention.prune` policy. It uses managed output `updated_at` timestamps. When both `keep_latest` and `older_than` are configured, it preserves the newest `keep_latest` outputs before applying the age policy.
+
+`--dry-run` does not delete outputs or rewrite state. `--apply` deletes only planned managed output paths, preserves unmanaged files, preserves `.distributor.json`, removes confirmed deleted records from state, and updates the state timestamp. If a delete fails after earlier deletes succeed, state is rewritten only for confirmed deletions; failed and unattempted output records remain so retry remains accurate.
+
+For single-owner state, the state owner must match the selected pipeline and destination. For shared-root state, pruning is scoped to the selected owner and preserves other owners.
+
 ## Dry Runs And Output Review
 
-`run --dry-run` loads config, resolves credentials, discovers source bundles, opens destinations, inspects destination state, builds publish plans, and prints actions. It does not write outputs, `.distributor.json`, or SSH `known_hosts` entries.
+`run --dry-run` loads config, resolves credentials, discovers source bundles, opens destinations, inspects destination state, builds publish plans, and prints actions. It does not write outputs, `.distributor.json`, or SSH `known_hosts` entries. For reconciliation, dry runs report the same high-level action labels as execution; inspect the configured destination's `reconciliation.mode` to determine whether `replace_older` will replace the managed set or merge into it.
+
+For shared-root destinations, dry runs are owner-scoped. A `replace_older` action replaces or merges only the current owner according to `reconciliation.mode`; unrelated owners remain managed by the shared-root state.
 
 Review these action labels before publishing:
 
-- `publish_new`: destination is empty and unmanaged.
+- `publish_new`: destination state is absent, or a shared-root owner is absent and planned paths are publishable.
 - `replace_older`: destination state is older than the source.
 - `skip_same`: destination state already matches the source.
 - `skip_destination_newer`: destination state is newer than the source and is skipped.
@@ -110,6 +181,8 @@ Forced replacement can claim unmanaged non-empty destination paths. State confli
 
 Forced replacement deletes the current destination bundle path before writing outputs and state. It does not delete parent paths, sibling paths, or storage outside the destination bundle path. For fixed destinations, the destination bundle path is the backend root, so a forced replacement can clear that configured root.
 
+For shared-root destinations, forced replacement also deletes the configured destination bundle path before writing new shared-root state. This removes unrelated owners inside that destination root. Preview with `--dry-run --force` and confirm the destination path before applying.
+
 `--force` applies only to the current invocation. There is no config field that enables forced replacement by default.
 
 ## HTTP Upload Operation
@@ -194,7 +267,7 @@ S3 execution uses the AWS SDK for Go v2. See [S3-Compatible Storage Integration]
 
 When explicit S3 credential variable names are configured, both must resolve to non-empty values through the process environment or `secrets.directory`. When omitted, the AWS SDK default credential chain is used as-is.
 
-Normal replacement and failed-write cleanup delete only managed output objects recorded in `.distributor.json` plus the state object. Forced replacement deletes objects under the bounded destination bundle prefix. Distributor does not manage bucket versioning or delete markers.
+Normal single-owner replacement and failed-write cleanup delete only managed output objects recorded in `.distributor.json` plus the state object. Shared-root replacement deletes only current-owner omitted output objects and rewrites the shared state object. Merge publication retains omitted managed objects and may overwrite existing managed objects. Forced replacement deletes objects under the bounded destination bundle prefix. Distributor does not manage bucket versioning or delete markers.
 
 ## Secrets Operation
 
@@ -209,7 +282,10 @@ Use these recovery boundaries:
 - For source validation failures, regenerate the source bundle and manifest together.
 - For an empty or missing destination, rerun after fixing config or storage access.
 - For unmanaged destination content, move unrelated files aside or use a different destination path before publishing.
-- For failed writes, inspect the destination bundle path, remove only confirmed partial outputs if needed, then rerun `--dry-run`.
+- For shared-root ownership conflicts, change one owner so it writes a different destination path, or use a separate destination root.
+- For missing managed output files recorded in state, run `reconcile-state --dry-run`, then apply `reconcile-state` if the missing files should no longer be considered managed.
+- For configured retention cleanup, run `prune --dry-run`, then apply `prune --apply` after reviewing the managed output list.
+- For failed writes, inspect the destination bundle path, remove only confirmed partial outputs if needed, then rerun `--dry-run`. In merge mode, retained outputs may be intentional managed outputs from the prior state.
 - For state conflicts, verify the source, pipeline, destination, and existing `.distributor.json` before considering `--force`.
 - For HTTP upload failures, inspect `/runs/<run-id>` while retained; after expiry or restart, rely on destination state and logs/output from the publishing run.
 

docs/policy/architecture.md

@@ -94,12 +94,19 @@ The source manifest should remain minimal. Routing, destination selection, publi
 
 `manifest.json` from the source bundle is not copied to destinations as destination state.
 
-Each destination bundle path is managed by `.distributor.json`. This file is both the destination sentinel and the destination state record. It records:
+Each destination bundle path is managed by `.distributor.json`. This file is both the destination sentinel and the destination state record.
+
+Publish execution writes single-owner or shared-root destination state according to destination `state.mode`. In shared-root state, one `.distributor.json` records multiple pipeline/destination owners and every managed output carries its owner identity.
+
+Single-owner state records:
 
 - `distributor` state schema version;
 - pipeline id;
 - destination id;
 - publication timestamp;
+- state creation and update timestamps;
+- single-owner state mode;
+- reconciliation mode;
 - the normalized source manifest used for publication;
 - metadata for copied source outputs;
 - metadata for generated outputs, such as HTML files;
@@ -110,11 +117,19 @@ A representative destination state file is:
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "distributor_version": "0.1.0",
   "pipeline_id": "weather-daily",
   "destination_id": "static-html",
   "published_at": "2026-05-30T11:12:00Z",
+  "created_at": "2026-05-30T11:12:00Z",
+  "updated_at": "2026-05-30T11:12:00Z",
+  "state": {
+    "mode": "single_owner"
+  },
+  "reconciliation": {
+    "mode": "replace"
+  },
   "source": {
     "manifest": {
       "schema_version": 1,
@@ -141,7 +156,9 @@ A representative destination state file is:
       "transform": "markdown_to_html",
       "sha256": "sha256:...",
       "size": 23456,
-      "url": "https://reports.example.com/weather-daily/"
+      "url": "https://reports.example.com/weather-daily/",
+      "created_at": "2026-05-30T11:12:00Z",
+      "updated_at": "2026-05-30T11:12:00Z"
     }
   ]
 }
@@ -156,6 +173,8 @@ Destination comparison rules are based on `.distributor.json`:
 - Existing state has the same source id and same `created` but different digest: fail as a conflict.
 - Existing state has a different source id: fail as a conflict.
 
+For older destination state, destination `reconciliation.mode` controls output updates. `replace` rewrites the managed output set to match the new plan. `merge` retains omitted managed outputs, overwrites only existing managed paths, and rejects planned paths that collide with unmanaged storage content.
+
 ## Publication and Transform Policy
 
 Source files are canonical bundle artifacts. Transform outputs are derived publication artifacts.

docs/roadmap/api.md

@@ -1,25 +0,0 @@
-# API Roadmap
-
-This document records API work that is not part of the current implementation. Current HTTP upload behavior is documented in `docs/integrations/http-upload.md`, current configuration behavior is documented in `docs/config.md`, and current producer package usage is documented under `docs/consumers/`.
-
-## Deferred Upload API Work
-
-- Durable upload status storage.
-- Durable idempotency records across server restarts.
-- Run listing, retry, and cancellation endpoints.
-- Long-polling or wait-for-completion workflows.
-- Multipart, resumable, or streaming upload protocols.
-- Additional archive content negotiation beyond tar and gzip-compressed tar.
-- URL-token authentication for constrained clients.
-- Upload token lifecycle tooling.
-- Mutual TLS or other in-app identity mechanisms.
-- In-app TLS termination.
-- In-app public exposure policy.
-- In-app upload rate limiting.
-
-## Boundaries
-
-- Producers do not choose destination ids, destination paths, transforms, links, publish policy, transfer policy, or storage backends through upload requests.
-- Source manifests remain free of routing, destination, transform, and credential data.
-- `http_upload` remains source-only unless a future design changes that contract.
-- Public access policy, TLS termination, and rate limiting belong in deployment infrastructure unless a future design changes that boundary.

docs/roadmap/future.md

@@ -33,6 +33,21 @@ internal docs.
 - Resumable upload support.
 - Streaming upload protocols.
 
+## Destination State Repair
+
+- Unmanaged-file adoption workflow for destination state repair.
+- Digest-audit mode for managed destination outputs.
+- Explicit invalid-state repair workflow.
+- Whole-config state repair command.
+
+## Destination Retention And Pruning
+
+- One-off retention overrides for `prune`.
+- Automatic post-publish pruning.
+- Path/date parsing retention policies.
+- Group-level pruning by source publication.
+- Removal of empty state files.
+
 ## Destination Backends
 
 - GitHub Gist destination backend support.
@@ -68,6 +83,7 @@ internal docs.
 - Mutual TLS or other in-app identity mechanisms.
 - In-app TLS.
 - Public exposure defaults.
+- In-app upload rate limiting.
 - Browser UI.
 
 ## Boundaries
@@ -76,5 +92,12 @@ internal docs.
   contract.
 - Current upload status, queue, and idempotency state are memory-only.
 - Producers submit complete tar or gzip-compressed tar source bundles today.
+- Producers do not choose destination ids, destination paths, transforms, links,
+  publish policy, transfer policy, storage backends, reconciliation mode, state
+  mode, or retention policy through upload requests.
+- Source manifests remain free of routing, destination, transform, credential,
+  reconciliation, state, and retention data.
 - Public access policy, TLS termination, and rate limiting belong outside
   `distributor` unless a future implementation changes that boundary.
+- `distributor` is not a broad storage synchronization tool unless a future
+  implementation explicitly changes that non-goal.

docs/roadmap/implementation.md

@@ -1,22 +0,0 @@
-# Upload API Implementation Notes
-
-This file has no active implementation tasks for the pipeline-scoped upload API.
-
-Current behavior is documented in:
-
-- `docs/config.md`
-- `docs/integrations/http-upload.md`
-- `docs/consumers/api.md`
-- `docs/consumers/pkg-upload.md`
-- `docs/operations.md`
-- `docs/troubleshooting.md`
-
-Deferred API work is tracked in `docs/roadmap/api.md` and broader deferred work is tracked in `docs/roadmap/future.md`.
-
-## Boundaries
-
-- Keep producer routing, destination selection, transform policy, publish policy, transfer policy, and backend credentials out of source manifests.
-- Keep `pkg/upload` focused on producer-side bundle submission and status polling.
-- Keep server-side upload authentication, authorization, queueing, status, and publish orchestration in `internal/app`.
-- Keep archive extraction and staged bundle validation in `internal/ingest`.
-- Keep durable status, durable idempotency, retry endpoints, cancellation endpoints, and wait helpers out of the current implementation until a new roadmap item defines them.

docs/troubleshooting.md

@@ -69,6 +69,42 @@ Safe fix: use either `distributor validate <path>` / `distributor inspect <path>
 
 Reference: [CLI](cli.md#validate).
 
+## Reconcile-State Selector Is Missing Or Wrong
+
+Symptom: `reconcile-state requires --config`, `requires --pipeline`, `requires --destination`, `pipeline "<id>" not found`, `destination <id> not found`, or `state owner is ... not ...`.
+
+Likely cause: the command did not identify one configured destination root, or the selected root contains state for a different single-owner pipeline/destination.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor reconcile-state --help
+rg -n 'pipelines:|destinations:|id:' <config-path>
+cat <destination-path>/.distributor.json
+```
+
+Safe fix: pass the configured `--config`, `--pipeline`, and `--destination` values that identify the destination root containing the state file. For unrelated single-owner state, use the correct config selector or a separate destination root; `reconcile-state` will not take over mismatched state.
+
+Reference: [CLI](cli.md#reconcile-state).
+
+## Prune Selector Or Mode Is Missing Or Wrong
+
+Symptom: `prune requires --config`, `requires --pipeline`, `requires --destination`, `requires exactly one of --dry-run or --apply`, `pipeline "<id>" not found`, `destination <id> not found`, or `state owner is ... not ...`.
+
+Likely cause: the command did not identify one configured destination root, did not choose exactly one execution mode, or the selected root contains state for a different single-owner pipeline/destination.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor prune --help
+rg -n 'retention:|prune:|pipelines:|destinations:|id:' <config-path>
+cat <destination-path>/.distributor.json
+```
+
+Safe fix: pass the configured `--config`, `--pipeline`, and `--destination` values that identify the destination root containing the state file. Use `--dry-run` for read-only review or `--apply` for deletion, but not both. For unrelated single-owner state, use the correct config selector or a separate destination root; `prune` will not take over mismatched state.
+
+Reference: [CLI](cli.md#prune).
+
 ## Output Format Is Invalid
 
 Symptom: `format must be text or json`.
@@ -182,6 +218,48 @@ Safe fix: verify the source and destination are intended to match. Use a separat
 
 Reference: [Operations](operations.md#destination-state-and-retry-behavior).
 
+## Destination State References Missing Managed Outputs
+
+Symptom: `reconcile-state --dry-run` reports `status=would_change` or JSON `missing_managed_outputs` entries.
+
+Likely cause: files that were recorded as managed in `.distributor.json` were removed outside `distributor`, or a previous external cleanup removed destination files without updating state.
+
+Diagnostic:
+
+```sh
+go run ./cmd/distributor reconcile-state \
+  --config <config-path> \
+  --pipeline <pipeline-id> \
+  --destination <destination-id> \
+  --dry-run
+```
+
+Safe fix: if the missing files should no longer be managed, rerun the same command without `--dry-run` to remove only the missing managed output records from `.distributor.json`. The command does not delete destination files or adopt unmanaged entries. If the files should exist, restore them from backup or republish instead.
+
+Reference: [Operations](operations.md#destination-state-repair).
+
+## Prune Reports No Planned Deletes
+
+Symptom: `prune --dry-run` reports `planned=0` or JSON `planned_outputs: []`.
+
+Likely cause: pruning is disabled for the selected destination, every managed output is preserved by `keep_latest`, no managed output is older than `older_than`, or the selected shared-root owner has no eligible outputs.
+
+Diagnostic:
+
+```sh
+rg -n 'retention:|prune:|older_than:|keep_latest:' <config-path>
+go run ./cmd/distributor prune \
+  --config <config-path> \
+  --pipeline <pipeline-id> \
+  --destination <destination-id> \
+  --dry-run \
+  --format json
+```
+
+Safe fix: verify the selected destination's retention policy and the managed output `updated_at` timestamps in `.distributor.json`. Adjust config if the policy is too conservative, then rerun `--dry-run` before using `--apply`.
+
+Reference: [Operations](operations.md#managed-output-pruning).
+
 ## Destination Is Newer Than Source
 
 Symptom: `skip_destination_newer` or `destination is newer and replacement requires --force`.
@@ -216,9 +294,9 @@ Reference: [Operations](operations.md#forced-replacement-workflow).
 
 ## Output Path Collision
 
-Symptom: `destination output path collision`.
+Symptom: `destination output path collision` or `merge output path ... exists but is not managed by destination state`.
 
-Likely cause: publication would write two outputs to the same destination path, such as copying `report.html` while also generating `report.html` from `report.md`.
+Likely cause: publication would write two outputs to the same destination path, such as copying `report.html` while also generating `report.html` from `report.md`. For merge reconciliation, it can also mean a planned output path already exists in storage but is not recorded in `.distributor.json` as managed.
 
 Diagnostic:
 
@@ -226,10 +304,44 @@ Diagnostic:
 go run ./cmd/distributor run --config <config-path> --dry-run
 ```
 
-Safe fix: adjust source files or publish/transform policy so copied and generated outputs do not collide.
+Safe fix: adjust source files or publish/transform policy so copied and generated outputs do not collide. For merge reconciliation, move unmanaged content aside, choose another destination path, or use replacement/forced replacement only when deleting the destination bundle path is intended.
 
 Reference: [Configuration](config.md#publish-and-transform-policy).
 
+## Shared-Root Ownership Conflict
+
+Symptom: `fail_conflict` with a reason like `destination output path ... is owned by <pipeline>/<destination>`.
+
+Likely cause: a `state.mode: shared_root` destination planned an output path already recorded in `.distributor.json` for another pipeline/destination owner.
+
+Diagnostic:
+
+```sh
+cat <destination-path>/.distributor.json
+go run ./cmd/distributor run --config <config-path> --dry-run
+```
+
+Safe fix: change one owner so it writes a different output path, use a separate destination root, or intentionally replace the whole destination root only after previewing with `--dry-run --force`.
+
+Reference: [Operations](operations.md#destination-state-and-retry-behavior).
+
+## Shared-Root Unmanaged Path Collision
+
+Symptom: `fail_unmanaged` with a reason like `destination output path ... exists but is not managed by destination state`.
+
+Likely cause: a `state.mode: shared_root` destination planned a new output path that already exists in storage but is not recorded as managed in `.distributor.json`.
+
+Diagnostic:
+
+```sh
+find <destination-path> -maxdepth 2 -print
+cat <destination-path>/.distributor.json
+```
+
+Safe fix: move the unmanaged file aside, change the planned output path, or use forced replacement only when deleting the configured destination root is intended.
+
+Reference: [Operations](operations.md#forced-replacement-workflow).
+
 ## Run Failed After Writing Some Files
 
 Symptom: a destination write failed and the command exited non-zero after partial work.
@@ -242,7 +354,7 @@ Diagnostic:
 find <destination-path> -maxdepth 2 -print
 ```
 
-Safe fix: inspect the destination bundle path printed in the error. `distributor` attempts to remove outputs from the failed attempt, but operators should verify the destination before retrying. Rerun `--dry-run` before publishing again.
+Safe fix: inspect the destination bundle path printed in the error. `distributor` attempts to remove outputs from the failed attempt, but operators should verify the destination before retrying. In merge mode, previously managed retained or overwritten outputs may remain intentionally. Rerun `--dry-run` before publishing again.
 
 Reference: [Operations](operations.md#destination-state-and-retry-behavior).
 

examples/merge-reconciliation.yml

@@ -0,0 +1,18 @@
+pipelines:
+  - id: example-merge-reconciliation
+    source:
+      backend: local
+      path: examples/source-bundle
+    destinations:
+      - id: local-merge-html
+        backend: local
+        path: workspace/published/merge-reconciliation
+        publish:
+          source: false
+          html: true
+        transform:
+          markdown_to_html:
+            enabled: true
+            mode: sidecar
+        reconciliation:
+          mode: merge

examples/shared-root.yml

@@ -0,0 +1,31 @@
+pipelines:
+  - id: example-shared-root-source
+    source:
+      backend: local
+      path: examples/source-bundle
+    destinations:
+      - id: shared-local-root
+        backend: local
+        path: workspace/published/shared-root
+        state:
+          mode: shared_root
+        publish:
+          source: true
+          html: false
+  - id: example-shared-root-html
+    source:
+      backend: local
+      path: examples/source-bundle
+    destinations:
+      - id: shared-local-root
+        backend: local
+        path: workspace/published/shared-root
+        state:
+          mode: shared_root
+        publish:
+          source: false
+          html: true
+        transform:
+          markdown_to_html:
+            enabled: true
+            mode: sidecar

internal/adapters/local/backend.go

@@ -199,10 +199,22 @@ func (b *Backend) HasAny(ctx context.Context, prefix string) (bool, error) {
 }
 
 func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	return b.deleteManagedTargets(ctx, storage.OpDeleteManagedBundle, func() ([]string, error) {
+		return storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	}, opts)
+}
+
+func (b *Backend) DeleteManagedOutputs(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	return b.deleteManagedTargets(ctx, storage.OpDeleteManagedOutputs, func() ([]string, error) {
+		return storage.ManagedOutputTargets(bundlePath, managedOutputPaths)
+	}, opts)
+}
+
+func (b *Backend) deleteManagedTargets(ctx context.Context, op string, targetsFunc func() ([]string, error), opts storage.DeleteOptions) error {
 	if err := ctx.Err(); err != nil {
 		return err
 	}
-	targets, err := storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	targets, err := targetsFunc()
 	if err != nil {
 		return err
 	}
@@ -213,20 +225,20 @@ func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, ma
 			return err
 		}
 		if nativePath == b.root {
-			return storage.NewError(storage.OpDeleteManagedBundle, backendName, logicalPath, storage.ErrInvalidPath, nil)
+			return storage.NewError(op, backendName, logicalPath, storage.ErrInvalidPath, nil)
 		}
 		info, err := os.Lstat(nativePath)
 		if err != nil {
 			if opts.IgnoreMissing && errors.Is(err, fs.ErrNotExist) {
 				continue
 			}
-			return b.translateError(storage.OpDeleteManagedBundle, logicalPath, err)
+			return b.translateError(op, logicalPath, err)
 		}
 		if info.IsDir() {
-			return storage.NewError(storage.OpDeleteManagedBundle, backendName, logicalPath, storage.ErrUnsupported, nil)
+			return storage.NewError(op, backendName, logicalPath, storage.ErrUnsupported, nil)
 		}
 		if err := os.Remove(nativePath); err != nil {
-			return b.translateError(storage.OpDeleteManagedBundle, logicalPath, err)
+			return b.translateError(op, logicalPath, err)
 		}
 		if opts.PruneEmptyDirs {
 			b.pruneEmptyParents(filepath.Dir(nativePath))

internal/adapters/s3/backend.go

@@ -205,15 +205,27 @@ func (b *Backend) HasAny(ctx context.Context, logicalPrefix string) (bool, error
 }
 
 func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	return b.deleteManagedTargets(ctx, storage.OpDeleteManagedBundle, func() ([]string, error) {
+		return storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	}, opts)
+}
+
+func (b *Backend) DeleteManagedOutputs(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	return b.deleteManagedTargets(ctx, storage.OpDeleteManagedOutputs, func() ([]string, error) {
+		return storage.ManagedOutputTargets(bundlePath, managedOutputPaths)
+	}, opts)
+}
+
+func (b *Backend) deleteManagedTargets(ctx context.Context, op string, targetsFunc func() ([]string, error), opts storage.DeleteOptions) error {
 	if err := ctx.Err(); err != nil {
 		return err
 	}
-	targets, err := storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	targets, err := targetsFunc()
 	if err != nil {
 		return err
 	}
 	for _, target := range targets {
-		if err := b.deleteObject(ctx, storage.OpDeleteManagedBundle, target, opts); err != nil {
+		if err := b.deleteObject(ctx, op, target, opts); err != nil {
 			return err
 		}
 	}

internal/adapters/ssh/backend.go

@@ -223,10 +223,22 @@ func (b *Backend) HasAny(ctx context.Context, prefix string) (bool, error) {
 }
 
 func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	return b.deleteManagedTargets(ctx, storage.OpDeleteManagedBundle, func() ([]string, error) {
+		return storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	}, opts)
+}
+
+func (b *Backend) DeleteManagedOutputs(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	return b.deleteManagedTargets(ctx, storage.OpDeleteManagedOutputs, func() ([]string, error) {
+		return storage.ManagedOutputTargets(bundlePath, managedOutputPaths)
+	}, opts)
+}
+
+func (b *Backend) deleteManagedTargets(ctx context.Context, op string, targetsFunc func() ([]string, error), opts storage.DeleteOptions) error {
 	if err := ctx.Err(); err != nil {
 		return err
 	}
-	targets, err := storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	targets, err := targetsFunc()
 	if err != nil {
 		return err
 	}
@@ -236,20 +248,20 @@ func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, ma
 			return err
 		}
 		if nativePath == b.root {
-			return storage.NewError(storage.OpDeleteManagedBundle, BackendName, target, storage.ErrInvalidPath, nil)
+			return storage.NewError(op, BackendName, target, storage.ErrInvalidPath, nil)
 		}
 		info, err := b.client.Lstat(nativePath)
 		if err != nil {
 			if opts.IgnoreMissing && isNotExist(err) {
 				continue
 			}
-			return b.translateError(storage.OpDeleteManagedBundle, target, err)
+			return b.translateError(op, target, err)
 		}
 		if info.IsDir() {
-			return storage.NewError(storage.OpDeleteManagedBundle, BackendName, target, storage.ErrUnsupported, nil)
+			return storage.NewError(op, BackendName, target, storage.ErrUnsupported, nil)
 		}
 		if err := b.client.Remove(nativePath); err != nil {
-			return b.translateError(storage.OpDeleteManagedBundle, target, err)
+			return b.translateError(op, target, err)
 		}
 		if opts.PruneEmptyDirs {
 			b.pruneEmptyParents(parentOf(target))

internal/app/prune.go

@@ -0,0 +1,339 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+)
+
+type PruneOptions struct {
+	ConfigPath    string
+	PipelineID    string
+	DestinationID string
+	DryRun        bool
+	Now           time.Time
+	Stdout        io.Writer
+	OutputFormat  OutputFormat
+}
+
+type PrunePlanOptions struct {
+	PipelineID    string
+	DestinationID string
+	Now           time.Time
+}
+
+type PrunePlanReport struct {
+	PipelineID       string              `json:"pipeline_id"`
+	DestinationID    string              `json:"destination_id"`
+	OwnerScope       PruneOwnerScope     `json:"owner_scope"`
+	Enabled          bool                `json:"enabled"`
+	CheckedCount     int                 `json:"checked_count"`
+	PrunedOutputs    []PruneOutputRecord `json:"pruned_outputs"`
+	PreservedOutputs []PruneOutputRecord `json:"preserved_outputs"`
+}
+
+type PruneReport struct {
+	PipelineID       string              `json:"pipeline_id"`
+	DestinationID    string              `json:"destination_id"`
+	Backend          string              `json:"backend"`
+	RootPath         string              `json:"root_path"`
+	OwnerScope       PruneOwnerScope     `json:"owner_scope"`
+	Enabled          bool                `json:"enabled"`
+	CheckedCount     int                 `json:"checked_count"`
+	PlannedOutputs   []PruneOutputRecord `json:"planned_outputs"`
+	DeletedOutputs   []PruneOutputRecord `json:"deleted_outputs"`
+	PreservedOutputs []PruneOutputRecord `json:"preserved_outputs"`
+	FailedOutput     *PruneOutputRecord  `json:"failed_output,omitempty"`
+	StateChanged     bool                `json:"state_changed"`
+	WouldChange      bool                `json:"would_change"`
+	DryRun           bool                `json:"dry_run"`
+}
+
+type PruneOwnerScope struct {
+	PipelineID    string `json:"pipeline_id"`
+	DestinationID string `json:"destination_id"`
+}
+
+type PruneOutputRecord struct {
+	Path      string           `json:"path"`
+	UpdatedAt string           `json:"updated_at"`
+	Owner     *PruneOwnerScope `json:"owner,omitempty"`
+}
+
+func Prune(ctx context.Context, options PruneOptions) (PruneReport, error) {
+	if err := ValidateOutputFormat(options.OutputFormat); err != nil {
+		return PruneReport{}, err
+	}
+	if err := ctx.Err(); err != nil {
+		return PruneReport{}, err
+	}
+
+	setup, err := loadRuntimeSetup(options.ConfigPath)
+	if err != nil {
+		return PruneReport{}, err
+	}
+	return pruneSetup(ctx, setup, options)
+}
+
+func pruneConfigWithBackendFactory(ctx context.Context, cfg config.Config, options PruneOptions, provider backendFactoryProvider) (PruneReport, error) {
+	setup, err := runtimeSetupFromConfig("", cfg)
+	if err != nil {
+		return PruneReport{}, err
+	}
+	return pruneSetupWithBackendFactory(ctx, setup, options, provider)
+}
+
+func pruneSetup(ctx context.Context, setup runtimeSetup, options PruneOptions) (PruneReport, error) {
+	return pruneSetupWithBackendFactory(ctx, setup, options, newBackendFactoryWithEnvironment)
+}
+
+func pruneSetupWithBackendFactory(ctx context.Context, setup runtimeSetup, options PruneOptions, provider backendFactoryProvider) (PruneReport, error) {
+	if err := requirePruneScope(options); err != nil {
+		return PruneReport{}, err
+	}
+	pipeline, ok := findPipeline(setup.Config, options.PipelineID)
+	if !ok {
+		return PruneReport{}, PipelineNotFoundError{ID: options.PipelineID}
+	}
+	destination, ok := findDestination(pipeline, options.DestinationID)
+	if !ok {
+		return PruneReport{}, fmt.Errorf("pipeline %s destination %s not found", options.PipelineID, options.DestinationID)
+	}
+
+	backends := provider(setup.Environment)
+	destinationBackend, err := backends.openDestination(ctx, destination)
+	if err != nil {
+		return PruneReport{}, err
+	}
+	defer closeBackend(destinationBackend)
+
+	report, err := executePrune(ctx, destinationBackend, pipeline, destination, options)
+	if err != nil {
+		return report, err
+	}
+	if err := WritePruneReport(options.Stdout, options.OutputFormat, report); err != nil {
+		return PruneReport{}, err
+	}
+	return report, nil
+}
+
+func requirePruneScope(options PruneOptions) error {
+	if options.PipelineID == "" {
+		return fmt.Errorf("pipeline id is required")
+	}
+	if options.DestinationID == "" {
+		return fmt.Errorf("destination id is required")
+	}
+	return nil
+}
+
+func executePrune(ctx context.Context, backend storage.Backend, pipeline config.Pipeline, destination config.Destination, options PruneOptions) (PruneReport, error) {
+	now := options.Now
+	if now.IsZero() {
+		now = time.Now().UTC()
+	} else {
+		now = now.UTC()
+	}
+
+	statePath, err := storage.StatePath("")
+	if err != nil {
+		return PruneReport{}, err
+	}
+	data, err := backend.ReadFile(ctx, statePath)
+	if err != nil {
+		return PruneReport{}, err
+	}
+	document, err := state.ParseDocument(data)
+	if err != nil {
+		return PruneReport{}, err
+	}
+
+	plan, err := PlanPrune(document, destination.Retention.Prune, PrunePlanOptions{
+		PipelineID:    pipeline.ID,
+		DestinationID: destination.ID,
+		Now:           now,
+	})
+	if err != nil {
+		return PruneReport{}, err
+	}
+	report := PruneReport{
+		PipelineID:       pipeline.ID,
+		DestinationID:    destination.ID,
+		Backend:          destination.Backend,
+		RootPath:         destinationRootPath(destination),
+		OwnerScope:       plan.OwnerScope,
+		Enabled:          plan.Enabled,
+		CheckedCount:     plan.CheckedCount,
+		PlannedOutputs:   plan.PrunedOutputs,
+		DeletedOutputs:   []PruneOutputRecord{},
+		PreservedOutputs: plan.PreservedOutputs,
+		DryRun:           options.DryRun,
+	}
+	report.WouldChange = options.DryRun && len(report.PlannedOutputs) > 0
+	if options.DryRun || len(report.PlannedOutputs) == 0 {
+		return report, nil
+	}
+
+	deletedPaths := make([]string, 0, len(report.PlannedOutputs))
+	for _, output := range report.PlannedOutputs {
+		err := backend.DeleteManagedOutputs(ctx, "", []string{output.Path}, storage.DeleteOptions{
+			IgnoreMissing:  true,
+			PruneEmptyDirs: true,
+		})
+		if err != nil {
+			failed := output
+			report.FailedOutput = &failed
+			if len(deletedPaths) > 0 {
+				changed, writeErr := removePrunedStateRecords(ctx, backend, statePath, document, state.CurrentOwnerScope(pipeline.ID, destination.ID), deletedPaths, now)
+				report.StateChanged = changed
+				report.DeletedOutputs = report.PlannedOutputs[:len(deletedPaths)]
+				if writeErr != nil {
+					return report, writeErr
+				}
+			}
+			return report, err
+		}
+		deletedPaths = append(deletedPaths, output.Path)
+	}
+
+	changed, err := removePrunedStateRecords(ctx, backend, statePath, document, state.CurrentOwnerScope(pipeline.ID, destination.ID), deletedPaths, now)
+	report.StateChanged = changed
+	report.DeletedOutputs = report.PlannedOutputs
+	return report, err
+}
+
+func removePrunedStateRecords(ctx context.Context, backend storage.Backend, statePath string, document state.StateDocument, scope state.OwnerScope, paths []string, now time.Time) (bool, error) {
+	if len(paths) == 0 {
+		return false, nil
+	}
+	if document.SingleOwner != nil {
+		next, changed := state.RemoveMissingOutputs(*document.SingleOwner, paths)
+		if !changed {
+			return false, nil
+		}
+		next.UpdatedAt = now
+		if err := state.Validate(next); err != nil {
+			return false, err
+		}
+		return true, writeRepairedState(ctx, backend, statePath, next)
+	}
+	if document.SharedRoot != nil {
+		next, changed := state.RemoveMissingSharedRootOwnerOutputs(*document.SharedRoot, scope, paths)
+		if !changed {
+			return false, nil
+		}
+		next.UpdatedAt = now
+		if err := state.ValidateSharedRoot(next); err != nil {
+			return false, err
+		}
+		return true, writeRepairedState(ctx, backend, statePath, next)
+	}
+	return false, fmt.Errorf("destination state document is empty")
+}
+
+func PlanPrune(document state.StateDocument, policy config.PrunePolicy, options PrunePlanOptions) (PrunePlanReport, error) {
+	scope := state.CurrentOwnerScope(options.PipelineID, options.DestinationID)
+	report := PrunePlanReport{
+		PipelineID:       options.PipelineID,
+		DestinationID:    options.DestinationID,
+		OwnerScope:       PruneOwnerScope{PipelineID: scope.PipelineID, DestinationID: scope.DestinationID},
+		Enabled:          policy.Enabled,
+		PrunedOutputs:    []PruneOutputRecord{},
+		PreservedOutputs: []PruneOutputRecord{},
+	}
+	if !policy.Enabled {
+		return report, nil
+	}
+
+	candidates, err := pruneCandidatesForDocument(document, scope)
+	if err != nil {
+		return PrunePlanReport{}, err
+	}
+	report.CheckedCount = len(candidates)
+	plan := state.PlanPrune(candidates, state.PrunePlanOptions{
+		Now:        options.Now,
+		OlderThan:  pruneOlderThan(policy),
+		KeepLatest: policy.KeepLatest,
+	})
+	report.PrunedOutputs = pruneOutputRecords(plan.Pruned)
+	report.PreservedOutputs = pruneOutputRecords(plan.Preserved)
+	return report, nil
+}
+
+func pruneCandidatesForDocument(document state.StateDocument, scope state.OwnerScope) ([]state.PruneCandidate, error) {
+	if document.SingleOwner != nil {
+		singleOwner := *document.SingleOwner
+		if singleOwner.PipelineID != scope.PipelineID || singleOwner.DestinationID != scope.DestinationID {
+			return nil, fmt.Errorf("state owner is %s/%s, not %s/%s", singleOwner.PipelineID, singleOwner.DestinationID, scope.PipelineID, scope.DestinationID)
+		}
+		return state.SingleOwnerPruneCandidates(singleOwner), nil
+	}
+	if document.SharedRoot != nil {
+		return state.SharedRootPruneCandidates(*document.SharedRoot, scope), nil
+	}
+	return nil, fmt.Errorf("destination state document is empty")
+}
+
+func pruneOlderThan(policy config.PrunePolicy) *time.Duration {
+	if policy.OlderThan == nil {
+		return nil
+	}
+	duration := policy.OlderThan.AsDuration()
+	return &duration
+}
+
+func pruneOutputRecords(candidates []state.PruneCandidate) []PruneOutputRecord {
+	records := make([]PruneOutputRecord, 0, len(candidates))
+	for _, candidate := range candidates {
+		var owner *PruneOwnerScope
+		if candidate.Owner != nil {
+			owner = &PruneOwnerScope{
+				PipelineID:    candidate.Owner.PipelineID,
+				DestinationID: candidate.Owner.DestinationID,
+			}
+		}
+		records = append(records, PruneOutputRecord{
+			Path:      candidate.Path,
+			UpdatedAt: candidate.UpdatedAt.UTC().Format(time.RFC3339),
+			Owner:     owner,
+		})
+	}
+	return records
+}
+
+func WritePruneReport(w io.Writer, format OutputFormat, report PruneReport) error {
+	if IsJSONOutput(format) {
+		return WriteJSONEnvelope(w, "prune", true, nil, report, nil)
+	}
+	return writePruneReportText(w, report)
+}
+
+func writePruneReportText(w io.Writer, report PruneReport) error {
+	if w == nil {
+		return nil
+	}
+	status := "unchanged"
+	if report.StateChanged {
+		status = "changed"
+	} else if report.WouldChange {
+		status = "would_change"
+	}
+	_, err := fmt.Fprintf(w, "Prune: pipeline=%s destination=%s backend=%s root=%s status=%s checked=%d planned=%d deleted=%d preserved=%d dry_run=%t\n",
+		report.PipelineID,
+		report.DestinationID,
+		report.Backend,
+		report.RootPath,
+		status,
+		report.CheckedCount,
+		len(report.PlannedOutputs),
+		len(report.DeletedOutputs),
+		len(report.PreservedOutputs),
+		report.DryRun,
+	)
+	return err
+}

internal/app/prune_test.go

@@ -0,0 +1,353 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage/fake"
+	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
+)
+
+func TestPlanPruneDisabledPolicy(t *testing.T) {
+	document := state.StateDocument{SingleOwner: &state.DistributorState{}}
+	report, err := PlanPrune(document, config.PrunePolicy{}, PrunePlanOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+	})
+	if err != nil {
+		t.Fatalf("PlanPrune() error = %v", err)
+	}
+	if report.Enabled || report.CheckedCount != 0 || len(report.PrunedOutputs) != 0 {
+		t.Fatalf("report = %#v, want disabled empty plan", report)
+	}
+}
+
+func TestPlanPruneSingleOwnerOutputs(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	olderThan := config.Duration(48 * time.Hour)
+	destinationState := pruneSingleOwnerState(now)
+
+	report, err := PlanPrune(state.StateDocument{SingleOwner: &destinationState}, config.PrunePolicy{
+		Enabled:   true,
+		OlderThan: &olderThan,
+	}, PrunePlanOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+		Now:           now,
+	})
+	if err != nil {
+		t.Fatalf("PlanPrune() error = %v", err)
+	}
+	if got, want := pruneRecordPaths(report.PrunedOutputs), "old.txt"; got != want {
+		t.Fatalf("pruned = %q, want %q", got, want)
+	}
+	if got, want := pruneRecordPaths(report.PreservedOutputs), "fresh.txt"; got != want {
+		t.Fatalf("preserved = %q, want %q", got, want)
+	}
+}
+
+func TestPlanPruneSharedRootCurrentOwnerOnly(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	keepLatest := 0
+	sharedRoot := pruneSharedRootState(now)
+
+	report, err := PlanPrune(state.StateDocument{SharedRoot: &sharedRoot}, config.PrunePolicy{
+		Enabled:    true,
+		KeepLatest: &keepLatest,
+	}, PrunePlanOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+		Now:           now,
+	})
+	if err != nil {
+		t.Fatalf("PlanPrune() error = %v", err)
+	}
+	if got, want := report.CheckedCount, 1; got != want {
+		t.Fatalf("checked count = %d, want %d", got, want)
+	}
+	if got, want := pruneRecordPaths(report.PrunedOutputs), "archive.txt"; got != want {
+		t.Fatalf("pruned = %q, want %q", got, want)
+	}
+}
+
+func TestPruneDryRunReportsPlannedDeletesWithoutDeletingOrRewritingState(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	backend := fake.New()
+	cfg := pruneS3Config(t, pruneOlderThanPolicy(48*time.Hour))
+	original := pruneSingleOwnerState(now)
+	writeFakeSingleOwnerStateForPrune(t, backend, original)
+	testutil.WriteFakeFile(t, backend, "unmanaged.txt", "keep")
+
+	report, err := pruneConfigWithBackendFactory(context.Background(), cfg, PruneOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+		DryRun:        true,
+		Now:           now,
+	}, fakeBackendFactoryProvider(t, map[string]storage.Backend{"s3:reports": backend}))
+	if err != nil {
+		t.Fatalf("pruneConfigWithBackendFactory() error = %v", err)
+	}
+	if !report.WouldChange || report.StateChanged || len(report.DeletedOutputs) != 0 {
+		t.Fatalf("report would_change=%t state_changed=%t deleted=%d, want dry-run only", report.WouldChange, report.StateChanged, len(report.DeletedOutputs))
+	}
+	if got, want := pruneRecordPaths(report.PlannedOutputs), "old.txt"; got != want {
+		t.Fatalf("planned outputs = %q, want %q", got, want)
+	}
+	testutil.AssertFakeFile(t, backend, "old.txt", "managed")
+	testutil.AssertFakeFile(t, backend, "fresh.txt", "managed")
+	testutil.AssertFakeFile(t, backend, "unmanaged.txt", "keep")
+	destinationState := readFakeSingleOwnerState(t, backend)
+	if got := strings.Join(state.ManagedOutputPaths(destinationState), ","); got != "old.txt,fresh.txt" {
+		t.Fatalf("state outputs = %q, want original outputs", got)
+	}
+	if !destinationState.UpdatedAt.Equal(original.UpdatedAt) {
+		t.Fatalf("state updated_at = %s, want original %s", destinationState.UpdatedAt, original.UpdatedAt)
+	}
+}
+
+func TestPruneApplyDeletesOnlyManagedOutputsAndUpdatesState(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	backend := fake.New()
+	cfg := pruneS3Config(t, pruneOlderThanPolicy(48*time.Hour))
+	writeFakeSingleOwnerStateForPrune(t, backend, pruneSingleOwnerState(now))
+	testutil.WriteFakeFile(t, backend, "unmanaged.txt", "keep")
+
+	report, err := pruneConfigWithBackendFactory(context.Background(), cfg, PruneOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+		Now:           now,
+	}, fakeBackendFactoryProvider(t, map[string]storage.Backend{"s3:reports": backend}))
+	if err != nil {
+		t.Fatalf("pruneConfigWithBackendFactory() error = %v", err)
+	}
+	if !report.StateChanged || report.WouldChange {
+		t.Fatalf("report state_changed=%t would_change=%t, want applied change", report.StateChanged, report.WouldChange)
+	}
+	if got, want := pruneRecordPaths(report.DeletedOutputs), "old.txt"; got != want {
+		t.Fatalf("deleted outputs = %q, want %q", got, want)
+	}
+	testutil.AssertFakeMissing(t, backend, "old.txt")
+	testutil.AssertFakeFile(t, backend, "fresh.txt", "managed")
+	testutil.AssertFakeFile(t, backend, "unmanaged.txt", "keep")
+	assertFakeStateExists(t, backend)
+	destinationState := readFakeSingleOwnerState(t, backend)
+	if got := strings.Join(state.ManagedOutputPaths(destinationState), ","); got != "fresh.txt" {
+		t.Fatalf("state outputs = %q, want fresh.txt", got)
+	}
+	if !destinationState.UpdatedAt.Equal(now) {
+		t.Fatalf("state updated_at = %s, want %s", destinationState.UpdatedAt, now)
+	}
+}
+
+func TestPruneApplyPreservesStateForFailedDeletes(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	backend := fake.New()
+	keepLatest := 0
+	cfg := pruneS3Config(t, config.PrunePolicy{Enabled: true, KeepLatest: &keepLatest})
+	writeFakeSingleOwnerStateForPrune(t, backend, pruneSingleOwnerState(now))
+	failingBackend := failingDeleteBackend{Backend: backend, failPath: "fresh.txt"}
+
+	report, err := pruneConfigWithBackendFactory(context.Background(), cfg, PruneOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+		Now:           now,
+	}, fakeBackendFactoryProvider(t, map[string]storage.Backend{"s3:reports": failingBackend}))
+	if err == nil {
+		t.Fatal("pruneConfigWithBackendFactory() error = nil, want delete failure")
+	}
+	if report.FailedOutput == nil || report.FailedOutput.Path != "fresh.txt" {
+		t.Fatalf("failed output = %#v, want fresh.txt", report.FailedOutput)
+	}
+	if got, want := pruneRecordPaths(report.DeletedOutputs), "old.txt"; got != want {
+		t.Fatalf("deleted outputs = %q, want %q", got, want)
+	}
+	testutil.AssertFakeMissing(t, backend, "old.txt")
+	testutil.AssertFakeFile(t, backend, "fresh.txt", "managed")
+	assertFakeStateExists(t, backend)
+	destinationState := readFakeSingleOwnerState(t, backend)
+	if got := strings.Join(state.ManagedOutputPaths(destinationState), ","); got != "fresh.txt" {
+		t.Fatalf("state outputs = %q, want only failed output preserved", got)
+	}
+}
+
+func TestPruneSharedRootPreservesOtherOwnersWhenScopedToCurrentOwner(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	backend := fake.New()
+	keepLatest := 0
+	cfg := pruneS3Config(t, config.PrunePolicy{Enabled: true, KeepLatest: &keepLatest})
+	writeFakeSharedRootStateForApp(t, backend, pruneSharedRootState(now))
+	testutil.WriteFakeFile(t, backend, "unmanaged.txt", "keep")
+
+	report, err := pruneConfigWithBackendFactory(context.Background(), cfg, PruneOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+		Now:           now,
+	}, fakeBackendFactoryProvider(t, map[string]storage.Backend{"s3:reports": backend}))
+	if err != nil {
+		t.Fatalf("pruneConfigWithBackendFactory() error = %v", err)
+	}
+	if got, want := pruneRecordPaths(report.DeletedOutputs), "archive.txt"; got != want {
+		t.Fatalf("deleted outputs = %q, want %q", got, want)
+	}
+	testutil.AssertFakeMissing(t, backend, "archive.txt")
+	testutil.AssertFakeFile(t, backend, "html.txt", "old")
+	testutil.AssertFakeFile(t, backend, "unmanaged.txt", "keep")
+	sharedRoot := readFakeSharedRootStateForApp(t, backend)
+	if got := strings.Join(sharedRoot.AllManagedOutputPaths(), ","); got != "html.txt" {
+		t.Fatalf("shared-root outputs = %q, want other owner output preserved", got)
+	}
+}
+
+func pruneSingleOwnerState(now time.Time) state.DistributorState {
+	manifest := testutil.ValidManifest(testutil.BundleOptions{})
+	publishedAt := now.Add(-96 * time.Hour)
+	return state.DistributorState{
+		SchemaVersion:      state.SchemaVersion,
+		PipelineID:         "reports",
+		DestinationID:      "archive",
+		PublishedAt:        publishedAt,
+		CreatedAt:          publishedAt,
+		UpdatedAt:          publishedAt,
+		State:              state.StatePolicy{Mode: state.StateModeSingleOwner},
+		Reconciliation:     state.ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
+		Source:             state.SourceState{Manifest: manifest},
+		DistributorVersion: "test",
+		Outputs: []state.OutputFile{{
+			Path:       "old.txt",
+			Kind:       state.OutputKindSource,
+			SourcePath: "report.md",
+			SHA256:     manifest.Files[0].SHA256,
+			Size:       manifest.Files[0].Size,
+			CreatedAt:  now.Add(-96 * time.Hour),
+			UpdatedAt:  now.Add(-72 * time.Hour),
+		}, {
+			Path:       "fresh.txt",
+			Kind:       state.OutputKindSource,
+			SourcePath: "summary.txt",
+			SHA256:     manifest.Files[1].SHA256,
+			Size:       manifest.Files[1].Size,
+			CreatedAt:  now.Add(-24 * time.Hour),
+			UpdatedAt:  now.Add(-24 * time.Hour),
+		}},
+	}
+}
+
+func pruneSharedRootState(now time.Time) state.SharedRootState {
+	manifest := testutil.ValidManifest(testutil.BundleOptions{})
+	archive := state.CurrentOwnerScope("reports", "archive")
+	html := state.CurrentOwnerScope("reports", "html")
+	return state.SharedRootState{
+		SchemaVersion:      state.SharedRootSchemaVersion,
+		DistributorVersion: "test",
+		CreatedAt:          now.Add(-96 * time.Hour),
+		UpdatedAt:          now.Add(-24 * time.Hour),
+		State:              state.StatePolicy{Mode: state.StateModeSharedRoot},
+		Owners: []state.OwnerRecord{{
+			Scope:          archive,
+			Reconciliation: state.ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
+			Source:         state.SourceState{Manifest: manifest},
+		}, {
+			Scope:          html,
+			Reconciliation: state.ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
+			Source:         state.SourceState{Manifest: manifest},
+		}},
+		Outputs: []state.SharedRootOutputFile{{
+			Path:          "archive.txt",
+			Kind:          state.OutputKindSource,
+			SourcePath:    "report.md",
+			SHA256:        manifest.Files[0].SHA256,
+			Size:          manifest.Files[0].Size,
+			Owner:         archive,
+			SourceID:      manifest.ID,
+			SourceDigest:  manifest.Digest,
+			SourceCreated: manifest.Created,
+			CreatedAt:     now.Add(-96 * time.Hour),
+			UpdatedAt:     now.Add(-72 * time.Hour),
+		}, {
+			Path:          "html.txt",
+			Kind:          state.OutputKindSource,
+			SourcePath:    "summary.txt",
+			SHA256:        manifest.Files[1].SHA256,
+			Size:          manifest.Files[1].Size,
+			Owner:         html,
+			SourceID:      manifest.ID,
+			SourceDigest:  manifest.Digest,
+			SourceCreated: manifest.Created,
+			CreatedAt:     now.Add(-96 * time.Hour),
+			UpdatedAt:     now.Add(-72 * time.Hour),
+		}},
+	}
+}
+
+func pruneRecordPaths(records []PruneOutputRecord) string {
+	paths := make([]string, 0, len(records))
+	for _, record := range records {
+		paths = append(paths, record.Path)
+	}
+	return strings.Join(paths, ",")
+}
+
+func pruneS3Config(t *testing.T, policy config.PrunePolicy) config.Config {
+	t.Helper()
+	cfg := config.Config{Pipelines: []config.Pipeline{{
+		ID:     "reports",
+		Source: config.Backend{Backend: config.BackendLocal, Path: t.TempDir()},
+		Destinations: []config.Destination{{
+			ID:      "archive",
+			Backend: config.BackendS3,
+			Bucket:  "reports",
+			Retention: config.RetentionPolicy{
+				Prune: policy,
+			},
+		}},
+	}}}
+	config.ApplyDefaults(&cfg)
+	return cfg
+}
+
+func pruneOlderThanPolicy(duration time.Duration) config.PrunePolicy {
+	value := config.Duration(duration)
+	return config.PrunePolicy{
+		Enabled:   true,
+		OlderThan: &value,
+	}
+}
+
+func writeFakeSingleOwnerStateForPrune(t *testing.T, backend *fake.Backend, destinationState state.DistributorState) {
+	t.Helper()
+	data, err := json.MarshalIndent(destinationState, "", "  ")
+	if err != nil {
+		t.Fatalf("marshal single-owner state: %v", err)
+	}
+	testutil.WriteFakeFile(t, backend, storage.StateFileName, string(append(data, '\n')))
+	for _, output := range destinationState.Outputs {
+		testutil.WriteFakeFile(t, backend, output.Path, "managed")
+	}
+}
+
+func assertFakeStateExists(t *testing.T, backend *fake.Backend) {
+	t.Helper()
+	if _, err := backend.Stat(context.Background(), storage.StateFileName); err != nil {
+		t.Fatalf("state file stat error = %v", err)
+	}
+}
+
+type failingDeleteBackend struct {
+	storage.Backend
+	failPath string
+}
+
+func (b failingDeleteBackend) DeleteManagedOutputs(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	for _, path := range managedOutputPaths {
+		if path == b.failPath {
+			return storage.NewError(storage.OpDeleteManagedOutputs, "fake", path, storage.ErrPermission, nil)
+		}
+	}
+	return b.Backend.DeleteManagedOutputs(ctx, bundlePath, managedOutputPaths, opts)
+}

internal/app/reconcile_state.go

@@ -0,0 +1,395 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"sort"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+)
+
+const reconcileStateWalkLimit = 10000
+
+type ReconcileStateOptions struct {
+	ConfigPath    string
+	PipelineID    string
+	DestinationID string
+	AllOwners     bool
+	DryRun        bool
+	Stdout        io.Writer
+	OutputFormat  OutputFormat
+}
+
+type ReconcileStateReport struct {
+	PipelineID            string                    `json:"pipeline_id"`
+	DestinationID         string                    `json:"destination_id"`
+	Backend               string                    `json:"backend"`
+	RootPath              string                    `json:"root_path"`
+	StateSchema           int                       `json:"state_schema"`
+	OwnerScope            *ReconcileStateOwnerScope `json:"owner_scope,omitempty"`
+	CheckedCount          int                       `json:"checked_count"`
+	MissingManagedOutputs []ReconcileStatePath      `json:"missing_managed_outputs"`
+	UnmanagedEntries      []ReconcileStateEntry     `json:"unmanaged_entries"`
+	Changed               bool                      `json:"changed"`
+	WouldChange           bool                      `json:"would_change"`
+	DryRun                bool                      `json:"dry_run"`
+}
+
+type ReconcileStateOwnerScope struct {
+	PipelineID    string `json:"pipeline_id"`
+	DestinationID string `json:"destination_id"`
+	AllOwners     bool   `json:"all_owners,omitempty"`
+}
+
+type ReconcileStatePath struct {
+	Path          string                    `json:"path"`
+	OwnerScope    *ReconcileStateOwnerScope `json:"owner_scope,omitempty"`
+	StorageStatus string                    `json:"storage_status"`
+}
+
+type ReconcileStateEntry struct {
+	Path string `json:"path"`
+	Type string `json:"type"`
+	Size int64  `json:"size,omitempty"`
+}
+
+func ReconcileState(ctx context.Context, options ReconcileStateOptions) (ReconcileStateReport, error) {
+	if err := ValidateOutputFormat(options.OutputFormat); err != nil {
+		return ReconcileStateReport{}, err
+	}
+	if err := ctx.Err(); err != nil {
+		return ReconcileStateReport{}, err
+	}
+
+	setup, err := loadRuntimeSetup(options.ConfigPath)
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+	return reconcileStateSetup(ctx, setup, options)
+}
+
+func reconcileStateConfigWithBackendFactory(ctx context.Context, cfg config.Config, options ReconcileStateOptions, provider backendFactoryProvider) (ReconcileStateReport, error) {
+	setup, err := runtimeSetupFromConfig("", cfg)
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+	return reconcileStateSetupWithBackendFactory(ctx, setup, options, provider)
+}
+
+func reconcileStateSetup(ctx context.Context, setup runtimeSetup, options ReconcileStateOptions) (ReconcileStateReport, error) {
+	return reconcileStateSetupWithBackendFactory(ctx, setup, options, newBackendFactoryWithEnvironment)
+}
+
+func reconcileStateSetupWithBackendFactory(ctx context.Context, setup runtimeSetup, options ReconcileStateOptions, provider backendFactoryProvider) (ReconcileStateReport, error) {
+	if err := requireReconcileStateScope(options); err != nil {
+		return ReconcileStateReport{}, err
+	}
+	pipeline, ok := findPipeline(setup.Config, options.PipelineID)
+	if !ok {
+		return ReconcileStateReport{}, PipelineNotFoundError{ID: options.PipelineID}
+	}
+	destination, ok := findDestination(pipeline, options.DestinationID)
+	if !ok {
+		return ReconcileStateReport{}, fmt.Errorf("pipeline %s destination %s not found", options.PipelineID, options.DestinationID)
+	}
+
+	backends := provider(setup.Environment)
+	destinationBackend, err := backends.openDestination(ctx, destination)
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+	defer closeBackend(destinationBackend)
+
+	report, err := buildReconcileStateReport(ctx, destinationBackend, pipeline, destination, options)
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+	if err := WriteReconcileStateReport(options.Stdout, options.OutputFormat, report); err != nil {
+		return ReconcileStateReport{}, err
+	}
+	return report, nil
+}
+
+func requireReconcileStateScope(options ReconcileStateOptions) error {
+	if options.PipelineID == "" {
+		return fmt.Errorf("pipeline id is required")
+	}
+	if options.DestinationID == "" {
+		return fmt.Errorf("destination id is required")
+	}
+	return nil
+}
+
+func findDestination(pipeline config.Pipeline, id string) (config.Destination, bool) {
+	for _, destination := range pipeline.Destinations {
+		if destination.ID == id {
+			return destination, true
+		}
+	}
+	return config.Destination{}, false
+}
+
+func buildReconcileStateReport(ctx context.Context, backend storage.Backend, pipeline config.Pipeline, destination config.Destination, options ReconcileStateOptions) (ReconcileStateReport, error) {
+	statePath, err := storage.StatePath("")
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+	data, err := backend.ReadFile(ctx, statePath)
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+	document, err := state.ParseDocument(data)
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+
+	report := ReconcileStateReport{
+		PipelineID:            pipeline.ID,
+		DestinationID:         destination.ID,
+		Backend:               destination.Backend,
+		RootPath:              destinationRootPath(destination),
+		MissingManagedOutputs: []ReconcileStatePath{},
+		UnmanagedEntries:      []ReconcileStateEntry{},
+		DryRun:                options.DryRun,
+	}
+	scope := state.CurrentOwnerScope(pipeline.ID, destination.ID)
+	if document.SingleOwner != nil {
+		return reconcileSingleOwnerState(ctx, backend, statePath, *document.SingleOwner, scope, report, options)
+	}
+	return reconcileSharedRootState(ctx, backend, statePath, *document.SharedRoot, scope, report, options)
+}
+
+func reconcileSingleOwnerState(ctx context.Context, backend storage.Backend, statePath string, destinationState state.DistributorState, scope state.OwnerScope, report ReconcileStateReport, options ReconcileStateOptions) (ReconcileStateReport, error) {
+	if destinationState.PipelineID != scope.PipelineID || destinationState.DestinationID != scope.DestinationID {
+		return ReconcileStateReport{}, fmt.Errorf("state owner is %s/%s, not %s/%s", destinationState.PipelineID, destinationState.DestinationID, scope.PipelineID, scope.DestinationID)
+	}
+	report.StateSchema = destinationState.SchemaVersion
+	report.OwnerScope = &ReconcileStateOwnerScope{PipelineID: scope.PipelineID, DestinationID: scope.DestinationID}
+	managed := state.ManagedOutputPaths(destinationState)
+	missing, err := missingSingleOwnerOutputs(ctx, backend, destinationState.Outputs)
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+	report.CheckedCount = len(managed)
+	report.MissingManagedOutputs = missing
+	unmanaged, err := unmanagedEntries(ctx, backend, managed)
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+	report.UnmanagedEntries = unmanaged
+	report.WouldChange = options.DryRun && len(missing) > 0
+
+	if !options.DryRun && len(missing) > 0 {
+		missingPaths := missingReportPaths(missing)
+		next, changed := state.RemoveMissingOutputs(destinationState, missingPaths)
+		report.Changed = changed
+		if changed {
+			next.UpdatedAt = time.Now().UTC()
+			if err := state.Validate(next); err != nil {
+				return ReconcileStateReport{}, err
+			}
+			if err := writeRepairedState(ctx, backend, statePath, next); err != nil {
+				return ReconcileStateReport{}, err
+			}
+		}
+	}
+	return report, nil
+}
+
+func reconcileSharedRootState(ctx context.Context, backend storage.Backend, statePath string, sharedRoot state.SharedRootState, scope state.OwnerScope, report ReconcileStateReport, options ReconcileStateOptions) (ReconcileStateReport, error) {
+	report.StateSchema = sharedRoot.SchemaVersion
+	report.OwnerScope = &ReconcileStateOwnerScope{
+		PipelineID:    scope.PipelineID,
+		DestinationID: scope.DestinationID,
+		AllOwners:     options.AllOwners,
+	}
+	managed := sharedRoot.AllManagedOutputPaths()
+	outputs := sharedRoot.Outputs
+	if !options.AllOwners {
+		outputs = sharedRootOutputsForOwner(sharedRoot.Outputs, scope)
+	}
+	missing, err := missingSharedRootOutputs(ctx, backend, outputs)
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+	report.CheckedCount = len(outputs)
+	report.MissingManagedOutputs = missing
+	unmanaged, err := unmanagedEntries(ctx, backend, managed)
+	if err != nil {
+		return ReconcileStateReport{}, err
+	}
+	report.UnmanagedEntries = unmanaged
+	report.WouldChange = options.DryRun && len(missing) > 0
+
+	if !options.DryRun && len(missing) > 0 {
+		missingPaths := missingReportPaths(missing)
+		var next state.SharedRootState
+		var changed bool
+		if options.AllOwners {
+			next, changed = state.RemoveMissingSharedRootOutputs(sharedRoot, missingPaths)
+		} else {
+			next, changed = state.RemoveMissingSharedRootOwnerOutputs(sharedRoot, scope, missingPaths)
+		}
+		report.Changed = changed
+		if changed {
+			next.UpdatedAt = time.Now().UTC()
+			if err := state.ValidateSharedRoot(next); err != nil {
+				return ReconcileStateReport{}, err
+			}
+			if err := writeRepairedState(ctx, backend, statePath, next); err != nil {
+				return ReconcileStateReport{}, err
+			}
+		}
+	}
+	return report, nil
+}
+
+func missingSingleOwnerOutputs(ctx context.Context, backend storage.Backend, outputs []state.OutputFile) ([]ReconcileStatePath, error) {
+	missing := make([]ReconcileStatePath, 0)
+	for _, output := range outputs {
+		if err := checkManagedOutput(ctx, backend, output.Path); err != nil {
+			if storage.IsNotFound(err) {
+				missing = append(missing, ReconcileStatePath{Path: output.Path, StorageStatus: "missing"})
+				continue
+			}
+			return nil, err
+		}
+	}
+	return missing, nil
+}
+
+func missingSharedRootOutputs(ctx context.Context, backend storage.Backend, outputs []state.SharedRootOutputFile) ([]ReconcileStatePath, error) {
+	missing := make([]ReconcileStatePath, 0)
+	for _, output := range outputs {
+		if err := checkManagedOutput(ctx, backend, output.Path); err != nil {
+			if storage.IsNotFound(err) {
+				missing = append(missing, ReconcileStatePath{
+					Path: output.Path,
+					OwnerScope: &ReconcileStateOwnerScope{
+						PipelineID:    output.Owner.PipelineID,
+						DestinationID: output.Owner.DestinationID,
+					},
+					StorageStatus: "missing",
+				})
+				continue
+			}
+			return nil, err
+		}
+	}
+	return missing, nil
+}
+
+func checkManagedOutput(ctx context.Context, backend storage.Backend, path string) error {
+	_, err := backend.Stat(ctx, path)
+	return err
+}
+
+func unmanagedEntries(ctx context.Context, backend storage.Backend, managedPaths []string) ([]ReconcileStateEntry, error) {
+	managed := make(map[string]struct{}, len(managedPaths)+1)
+	for _, path := range managedPaths {
+		managed[path] = struct{}{}
+	}
+	managed[storage.StateFileName] = struct{}{}
+
+	entries := make([]ReconcileStateEntry, 0)
+	err := backend.Walk(ctx, "", storage.WalkOptions{Recursive: true, Limit: reconcileStateWalkLimit}, func(entry storage.Entry) error {
+		if entry.Type == storage.EntryTypeDirectory {
+			return nil
+		}
+		if _, ok := managed[entry.Path]; ok {
+			return nil
+		}
+		entries = append(entries, ReconcileStateEntry{
+			Path: entry.Path,
+			Type: string(entry.Type),
+			Size: entry.Size,
+		})
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	sort.Slice(entries, func(i, j int) bool {
+		return entries[i].Path < entries[j].Path
+	})
+	return entries, nil
+}
+
+func sharedRootOutputsForOwner(outputs []state.SharedRootOutputFile, scope state.OwnerScope) []state.SharedRootOutputFile {
+	selected := make([]state.SharedRootOutputFile, 0, len(outputs))
+	for _, output := range outputs {
+		if output.Owner == scope {
+			selected = append(selected, output)
+		}
+	}
+	return selected
+}
+
+func missingReportPaths(missing []ReconcileStatePath) []string {
+	paths := make([]string, 0, len(missing))
+	for _, item := range missing {
+		paths = append(paths, item.Path)
+	}
+	return paths
+}
+
+func writeRepairedState(ctx context.Context, backend storage.Backend, path string, value any) error {
+	data, err := json.MarshalIndent(value, "", "  ")
+	if err != nil {
+		return err
+	}
+	data = append(data, '\n')
+	_, err = backend.WriteFile(ctx, path, data, storage.WriteOptions{Overwrite: true, PreferAtomic: true})
+	return err
+}
+
+func destinationRootPath(destination config.Destination) string {
+	switch destination.Backend {
+	case config.BackendS3:
+		if destination.Prefix == "" {
+			return "."
+		}
+		return destination.Prefix
+	default:
+		if destination.Path == "" {
+			return "."
+		}
+		return destination.Path
+	}
+}
+
+func WriteReconcileStateReport(w io.Writer, format OutputFormat, report ReconcileStateReport) error {
+	if IsJSONOutput(format) {
+		return WriteJSONEnvelope(w, "reconcile-state", true, nil, report, nil)
+	}
+	return writeReconcileStateReportText(w, report)
+}
+
+func writeReconcileStateReportText(w io.Writer, report ReconcileStateReport) error {
+	if w == nil {
+		return nil
+	}
+	status := "unchanged"
+	if report.Changed {
+		status = "changed"
+	} else if report.WouldChange {
+		status = "would_change"
+	}
+	_, err := fmt.Fprintf(w, "Reconcile state: pipeline=%s destination=%s backend=%s root=%s status=%s checked=%d missing=%d unmanaged=%d dry_run=%t\n",
+		report.PipelineID,
+		report.DestinationID,
+		report.Backend,
+		report.RootPath,
+		status,
+		report.CheckedCount,
+		len(report.MissingManagedOutputs),
+		len(report.UnmanagedEntries),
+		report.DryRun,
+	)
+	return err
+}

internal/app/reconcile_state_test.go

@@ -0,0 +1,269 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage/fake"
+	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
+)
+
+func TestReconcileStateDryRunReportsMissingManagedOutputsWithoutRewrite(t *testing.T) {
+	backend := fake.New()
+	cfg := reconcileStateS3Config(t)
+	manifest := testutil.ValidManifest(testutil.BundleOptions{})
+	testutil.WriteFakeDestinationState(t, backend, "", manifest, testutil.DestinationStateOptions{})
+	if err := backend.DeleteManagedOutputs(context.Background(), "", []string{"summary.txt"}, storage.DeleteOptions{}); err != nil {
+		t.Fatalf("delete managed output: %v", err)
+	}
+	testutil.WriteFakeFile(t, backend, "extra.txt", "unmanaged")
+
+	report, err := reconcileStateConfigWithBackendFactory(context.Background(), cfg, ReconcileStateOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+		DryRun:        true,
+	}, fakeBackendFactoryProvider(t, map[string]storage.Backend{"s3:reports": backend}))
+	if err != nil {
+		t.Fatalf("reconcileStateConfigWithBackendFactory() error = %v", err)
+	}
+	if !report.WouldChange || report.Changed {
+		t.Fatalf("report changed=%t would_change=%t, want dry-run pending change", report.Changed, report.WouldChange)
+	}
+	if got := reportPathList(report.MissingManagedOutputs); got != "summary.txt" {
+		t.Fatalf("missing outputs = %q, want summary.txt", got)
+	}
+	if got := entryPathList(report.UnmanagedEntries); got != "extra.txt" {
+		t.Fatalf("unmanaged entries = %q, want extra.txt", got)
+	}
+	destinationState := readFakeSingleOwnerState(t, backend)
+	if got := strings.Join(state.ManagedOutputPaths(destinationState), ","); got != "report.md,summary.txt" {
+		t.Fatalf("state outputs = %q, want original outputs", got)
+	}
+}
+
+func TestReconcileStateApplyRemovesMissingRecordsAndPreservesUnmanagedFiles(t *testing.T) {
+	backend := fake.New()
+	cfg := reconcileStateS3Config(t)
+	manifest := testutil.ValidManifest(testutil.BundleOptions{})
+	testutil.WriteFakeDestinationState(t, backend, "", manifest, testutil.DestinationStateOptions{})
+	if err := backend.DeleteManagedOutputs(context.Background(), "", []string{"summary.txt"}, storage.DeleteOptions{}); err != nil {
+		t.Fatalf("delete managed output: %v", err)
+	}
+	testutil.WriteFakeFile(t, backend, "extra.txt", "unmanaged")
+
+	report, err := reconcileStateConfigWithBackendFactory(context.Background(), cfg, ReconcileStateOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+	}, fakeBackendFactoryProvider(t, map[string]storage.Backend{"s3:reports": backend}))
+	if err != nil {
+		t.Fatalf("reconcileStateConfigWithBackendFactory() error = %v", err)
+	}
+	if !report.Changed || report.WouldChange {
+		t.Fatalf("report changed=%t would_change=%t, want applied change", report.Changed, report.WouldChange)
+	}
+	destinationState := readFakeSingleOwnerState(t, backend)
+	if err := state.Validate(destinationState); err != nil {
+		t.Fatalf("Validate() repaired state error = %v", err)
+	}
+	if got := strings.Join(state.ManagedOutputPaths(destinationState), ","); got != "report.md" {
+		t.Fatalf("state outputs = %q, want report.md", got)
+	}
+	testutil.AssertFakeFile(t, backend, "extra.txt", "unmanaged")
+}
+
+func TestReconcileStateInvalidStateFailsWithoutRewrite(t *testing.T) {
+	backend := fake.New()
+	cfg := reconcileStateS3Config(t)
+	invalid := `{"schema_version":2,"pipeline_id":"reports"}`
+	testutil.WriteFakeFile(t, backend, storage.StateFileName, invalid)
+
+	_, err := reconcileStateConfigWithBackendFactory(context.Background(), cfg, ReconcileStateOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+	}, fakeBackendFactoryProvider(t, map[string]storage.Backend{"s3:reports": backend}))
+	if err == nil {
+		t.Fatal("reconcileStateConfigWithBackendFactory() error = nil, want invalid state error")
+	}
+	data, readErr := backend.ReadFile(context.Background(), storage.StateFileName)
+	if readErr != nil {
+		t.Fatalf("read invalid state: %v", readErr)
+	}
+	if string(data) != invalid {
+		t.Fatalf("state data = %q, want original invalid data", data)
+	}
+}
+
+func TestReconcileStateSharedRootOwnerScopeRepairsCurrentOwnerOnly(t *testing.T) {
+	backend := fake.New()
+	cfg := reconcileStateS3Config(t)
+	sharedRoot := reconcileSharedRootFixture(t)
+	writeFakeSharedRootStateForApp(t, backend, sharedRoot)
+	if err := backend.DeleteManagedOutputs(context.Background(), "", []string{"report.md", "report.html"}, storage.DeleteOptions{}); err != nil {
+		t.Fatalf("delete managed outputs: %v", err)
+	}
+
+	report, err := reconcileStateConfigWithBackendFactory(context.Background(), cfg, ReconcileStateOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+	}, fakeBackendFactoryProvider(t, map[string]storage.Backend{"s3:reports": backend}))
+	if err != nil {
+		t.Fatalf("reconcileStateConfigWithBackendFactory() error = %v", err)
+	}
+	if !report.Changed {
+		t.Fatal("report changed = false, want true")
+	}
+	repaired := readFakeSharedRootStateForApp(t, backend)
+	if got := strings.Join(repaired.AllManagedOutputPaths(), ","); got != "report.html" {
+		t.Fatalf("shared-root outputs = %q, want other owner output preserved", got)
+	}
+}
+
+func TestReconcileStateSharedRootAllOwnersRepairsEveryOwner(t *testing.T) {
+	backend := fake.New()
+	cfg := reconcileStateS3Config(t)
+	sharedRoot := reconcileSharedRootFixture(t)
+	writeFakeSharedRootStateForApp(t, backend, sharedRoot)
+	if err := backend.DeleteManagedOutputs(context.Background(), "", []string{"report.md", "report.html"}, storage.DeleteOptions{}); err != nil {
+		t.Fatalf("delete managed outputs: %v", err)
+	}
+
+	report, err := reconcileStateConfigWithBackendFactory(context.Background(), cfg, ReconcileStateOptions{
+		PipelineID:    "reports",
+		DestinationID: "archive",
+		AllOwners:     true,
+	}, fakeBackendFactoryProvider(t, map[string]storage.Backend{"s3:reports": backend}))
+	if err != nil {
+		t.Fatalf("reconcileStateConfigWithBackendFactory() error = %v", err)
+	}
+	if !report.Changed || report.CheckedCount != 2 {
+		t.Fatalf("report changed=%t checked=%d, want all-owner repair", report.Changed, report.CheckedCount)
+	}
+	repaired := readFakeSharedRootStateForApp(t, backend)
+	if got := repaired.AllManagedOutputPaths(); len(got) != 0 {
+		t.Fatalf("shared-root outputs = %#v, want none", got)
+	}
+}
+
+func reconcileStateS3Config(t *testing.T) config.Config {
+	t.Helper()
+	cfg := config.Config{Pipelines: []config.Pipeline{{
+		ID:     "reports",
+		Source: config.Backend{Backend: config.BackendLocal, Path: t.TempDir()},
+		Destinations: []config.Destination{{
+			ID:      "archive",
+			Backend: config.BackendS3,
+			Bucket:  "reports",
+		}},
+	}}}
+	config.ApplyDefaults(&cfg)
+	return cfg
+}
+
+func readFakeSingleOwnerState(t *testing.T, backend *fake.Backend) state.DistributorState {
+	t.Helper()
+	data, err := backend.ReadFile(context.Background(), storage.StateFileName)
+	if err != nil {
+		t.Fatalf("read state: %v", err)
+	}
+	destinationState, err := state.Parse(data)
+	if err != nil {
+		t.Fatalf("parse state: %v", err)
+	}
+	return destinationState
+}
+
+func writeFakeSharedRootStateForApp(t *testing.T, backend *fake.Backend, sharedRoot state.SharedRootState) {
+	t.Helper()
+	data, err := json.MarshalIndent(sharedRoot, "", "  ")
+	if err != nil {
+		t.Fatalf("marshal shared-root state: %v", err)
+	}
+	testutil.WriteFakeFile(t, backend, storage.StateFileName, string(append(data, '\n')))
+	for _, output := range sharedRoot.Outputs {
+		testutil.WriteFakeFile(t, backend, output.Path, "old")
+	}
+}
+
+func readFakeSharedRootStateForApp(t *testing.T, backend *fake.Backend) state.SharedRootState {
+	t.Helper()
+	data, err := backend.ReadFile(context.Background(), storage.StateFileName)
+	if err != nil {
+		t.Fatalf("read shared-root state: %v", err)
+	}
+	sharedRoot, err := state.ParseSharedRoot(data)
+	if err != nil {
+		t.Fatalf("parse shared-root state: %v", err)
+	}
+	return sharedRoot
+}
+
+func reconcileSharedRootFixture(t *testing.T) state.SharedRootState {
+	t.Helper()
+	source := testutil.ValidManifest(testutil.BundleOptions{})
+	htmlSource := source
+	createdAt := time.Date(2026, 5, 30, 11, 12, 0, 0, time.UTC)
+	return state.SharedRootState{
+		SchemaVersion:      state.SharedRootSchemaVersion,
+		DistributorVersion: "test",
+		CreatedAt:          createdAt,
+		UpdatedAt:          createdAt,
+		State:              state.StatePolicy{Mode: state.StateModeSharedRoot},
+		Owners: []state.OwnerRecord{{
+			Scope:          state.CurrentOwnerScope("reports", "archive"),
+			Reconciliation: state.ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
+			Source:         state.SourceState{Manifest: source},
+		}, {
+			Scope:          state.CurrentOwnerScope("reports", "html"),
+			Reconciliation: state.ReconciliationPolicy{Mode: config.ReconciliationModeMerge},
+			Source:         state.SourceState{Manifest: htmlSource},
+		}},
+		Outputs: []state.SharedRootOutputFile{{
+			Path:          "report.md",
+			Kind:          state.OutputKindSource,
+			SourcePath:    "report.md",
+			SHA256:        source.Files[0].SHA256,
+			Size:          source.Files[0].Size,
+			Owner:         state.CurrentOwnerScope("reports", "archive"),
+			SourceID:      source.ID,
+			SourceDigest:  source.Digest,
+			SourceCreated: source.Created,
+			CreatedAt:     createdAt,
+			UpdatedAt:     createdAt,
+		}, {
+			Path:          "report.html",
+			Kind:          state.OutputKindGenerated,
+			SourcePath:    "report.md",
+			Transform:     "markdown_to_html",
+			SHA256:        "sha256:" + strings.Repeat("a", 64),
+			Size:          128,
+			Owner:         state.CurrentOwnerScope("reports", "html"),
+			SourceID:      htmlSource.ID,
+			SourceDigest:  htmlSource.Digest,
+			SourceCreated: htmlSource.Created,
+			CreatedAt:     createdAt,
+			UpdatedAt:     createdAt,
+		}},
+	}
+}
+
+func reportPathList(paths []ReconcileStatePath) string {
+	values := make([]string, 0, len(paths))
+	for _, path := range paths {
+		values = append(values, path.Path)
+	}
+	return strings.Join(values, ",")
+}
+
+func entryPathList(entries []ReconcileStateEntry) string {
+	values := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		values = append(values, entry.Path)
+	}
+	return strings.Join(values, ",")
+}

internal/app/run_destination.go

@@ -69,6 +69,8 @@ func processDestinationSelection(ctx context.Context, request runDestinationRequ
 		Publish:               *request.destination.Publish,
 		Transform:             request.destination.Transform,
 		Links:                 request.destination.Links,
+		State:                 request.destination.State,
+		Reconciliation:        request.destination.Reconciliation,
 		Transformers:          request.transforms,
 		Transfer:              request.destination.Transfer,
 		DistributorVersion:    Version,

internal/app/run_test.go

@@ -15,6 +15,7 @@ import (
 	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
 	"gitea.maximumdirect.net/eric/distributor/internal/config"
 	"gitea.maximumdirect.net/eric/distributor/internal/notify"
+	"gitea.maximumdirect.net/eric/distributor/internal/publish"
 	"gitea.maximumdirect.net/eric/distributor/internal/state"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage/fake"
@@ -221,6 +222,67 @@ func TestRunPublishesNewLocalBundle(t *testing.T) {
 	}
 }
 
+func TestRunSharedRootDryRunWritesNoOutputsOrState(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	writeSourceBundle(t, sourceRoot, "", testBundleOptions{
+		Files: []testFile{{Path: "report.md", Data: "# Report\n"}},
+	})
+	configPath := writeSharedRootLocalConfig(t, sourceRoot, destinationRoot)
+
+	cfg, err := config.LoadFile(configPath)
+	if err != nil {
+		t.Fatalf("load config: %v", err)
+	}
+	report, err := buildRunReportWithBackendFactory(context.Background(), cfg, RunOptions{DryRun: true}, newBackendFactoryWithEnvironment)
+	if err != nil {
+		t.Fatalf("dry-run buildRunReportWithBackendFactory() error = %v", err)
+	}
+	if got, want := report.Actions[0].Action, string(publish.ActionPublishNew); got != want {
+		t.Fatalf("dry-run action = %q, want %q", got, want)
+	}
+	if _, statErr := os.Stat(filepath.Join(destinationRoot, "report.md")); !os.IsNotExist(statErr) {
+		t.Fatalf("output stat error = %v, want absent", statErr)
+	}
+	if _, statErr := os.Stat(filepath.Join(destinationRoot, storage.StateFileName)); !os.IsNotExist(statErr) {
+		t.Fatalf("state file stat error = %v, want absent", statErr)
+	}
+}
+
+func TestRunPublishesTwoPipelinesIntoSharedRoot(t *testing.T) {
+	firstSourceRoot := t.TempDir()
+	secondSourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	writeSourceBundle(t, firstSourceRoot, "", testBundleOptions{
+		ID:    "reports.first",
+		Files: []testFile{{Path: "first.md", Data: "# First\n"}},
+	})
+	writeSourceBundle(t, secondSourceRoot, "", testBundleOptions{
+		ID:    "reports.second",
+		Files: []testFile{{Path: "second.md", Data: "# Second\n"}},
+	})
+
+	err := Run(context.Background(), RunOptions{ConfigPath: writeTwoPipelineSharedRootConfig(t, firstSourceRoot, secondSourceRoot, destinationRoot)})
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	testutil.AssertFile(t, filepath.Join(destinationRoot, "first.md"), "# First\n")
+	testutil.AssertFile(t, filepath.Join(destinationRoot, "second.md"), "# Second\n")
+	destinationState := readSharedRootStateFile(t, filepath.Join(destinationRoot, storage.StateFileName))
+	if got, want := len(destinationState.Owners), 2; got != want {
+		t.Fatalf("owner count = %d, want %d", got, want)
+	}
+	if _, ok := destinationState.Owner(state.CurrentOwnerScope("reports-first", "archive")); !ok {
+		t.Fatal("reports-first/archive owner missing")
+	}
+	if _, ok := destinationState.Owner(state.CurrentOwnerScope("reports-second", "archive")); !ok {
+		t.Fatal("reports-second/archive owner missing")
+	}
+	if got, want := strings.Join(destinationState.AllManagedOutputPaths(), ","), "first.md,second.md"; got != want {
+		t.Fatalf("managed paths = %q, want %q", got, want)
+	}
+}
+
 func TestRunPipelineWithLocalSourcePublishesConfiguredDestination(t *testing.T) {
 	sourceRoot := t.TempDir()
 	destinationRoot := t.TempDir()
@@ -790,6 +852,53 @@ func TestRunNotifiesAfterReplacement(t *testing.T) {
 	}
 }
 
+func TestRunMergeReconciliationRetainsManagedOutput(t *testing.T) {
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	manifest := testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\nNew.\n"}},
+	})
+	older := manifest
+	older.Created = older.Created.Add(-time.Hour)
+	defaultManifest := testutil.ValidManifest(testutil.BundleOptions{})
+	older.Files = append([]bundle.ManifestFile(nil), defaultManifest.Files...)
+	older.Digest = bundle.BundleDigest(older.Files)
+	writeDestinationState(t, destinationRoot, "", older)
+	if err := os.WriteFile(filepath.Join(destinationRoot, "report.md"), []byte("old\n"), 0o600); err != nil {
+		t.Fatalf("write old report: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(destinationRoot, "summary.txt"), []byte("old summary\n"), 0o600); err != nil {
+		t.Fatalf("write old summary: %v", err)
+	}
+	configPath := writeConfigFile(t, `
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: `+sourceRoot+`
+    destinations:
+      - id: archive
+        backend: local
+        path: `+destinationRoot+`
+        reconciliation:
+          mode: merge
+`)
+
+	err := Run(context.Background(), RunOptions{ConfigPath: configPath})
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	testutil.AssertFile(t, filepath.Join(destinationRoot, "report.md"), "# Report\nNew.\n")
+	testutil.AssertFile(t, filepath.Join(destinationRoot, "summary.txt"), "old summary\n")
+	destinationState := readStateFile(t, filepath.Join(destinationRoot, storage.StateFileName))
+	if got, want := destinationState.Reconciliation.Mode, config.ReconciliationModeMerge; got != want {
+		t.Fatalf("reconciliation mode = %q, want %q", got, want)
+	}
+	if got, want := len(destinationState.Outputs), 2; got != want {
+		t.Fatalf("state output count = %d, want %d", got, want)
+	}
+}
+
 func TestRunJSONIncludesGeneratedOutputMetadata(t *testing.T) {
 	sourceRoot := t.TempDir()
 	destinationRoot := t.TempDir()
@@ -1670,6 +1779,50 @@ func writeLocalConfig(t *testing.T, sourceRoot, destinationRoot string) string {
 	return testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot)
 }
 
+func writeSharedRootLocalConfig(t *testing.T, sourceRoot, destinationRoot string) string {
+	t.Helper()
+	return writeConfigFile(t, `
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: `+sourceRoot+`
+    destinations:
+      - id: archive
+        backend: local
+        path: `+destinationRoot+`
+        state:
+          mode: shared_root
+`)
+}
+
+func writeTwoPipelineSharedRootConfig(t *testing.T, firstSourceRoot, secondSourceRoot, destinationRoot string) string {
+	t.Helper()
+	return writeConfigFile(t, `
+pipelines:
+  - id: reports-first
+    source:
+      backend: local
+      path: `+firstSourceRoot+`
+    destinations:
+      - id: archive
+        backend: local
+        path: `+destinationRoot+`
+        state:
+          mode: shared_root
+  - id: reports-second
+    source:
+      backend: local
+      path: `+secondSourceRoot+`
+    destinations:
+      - id: archive
+        backend: local
+        path: `+destinationRoot+`
+        state:
+          mode: shared_root
+`)
+}
+
 func writeFanoutConfig(t *testing.T, sourceRoot, firstDestination, secondDestination string) string {
 	t.Helper()
 	return testutil.WriteFanoutLocalConfig(t, sourceRoot, firstDestination, secondDestination)
@@ -1750,6 +1903,19 @@ func readStateFile(t *testing.T, path string) state.DistributorState {
 	return testutil.ReadDestinationState(t, path)
 }
 
+func readSharedRootStateFile(t *testing.T, path string) state.SharedRootState {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read shared-root state: %v", err)
+	}
+	destinationState, err := state.ParseSharedRoot(data)
+	if err != nil {
+		t.Fatalf("parse shared-root state: %v", err)
+	}
+	return destinationState
+}
+
 func outputsByPath(outputs []state.OutputFile) map[string]state.OutputFile {
 	byPath := make(map[string]state.OutputFile, len(outputs))
 	for _, output := range outputs {

internal/cli/prune.go

@@ -0,0 +1,88 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/app"
+)
+
+func pruneCommand(ctx context.Context, args []string, stdout, stderr io.Writer) int {
+	if hasHelp(args) {
+		printPruneHelp(stdout)
+		return exitOK
+	}
+
+	flags := newFlagSet("prune", stderr)
+	configPath := flags.String("config", "", "path to config file")
+	pipelineID := flags.String("pipeline", "", "pipeline id")
+	destinationID := flags.String("destination", "", "destination id")
+	dryRun := flags.Bool("dry-run", false, "report planned deletes without deleting outputs or rewriting state")
+	apply := flags.Bool("apply", false, "delete planned managed outputs and rewrite state")
+	formatFlag := addFormatFlag(flags)
+	if err := flags.Parse(args); err != nil {
+		return exitUsage
+	}
+	if rejectPositionalArgs(stderr, "prune", flags.Args()) {
+		return exitUsage
+	}
+	format, ok := parseOutputFormat(stderr, "prune", *formatFlag)
+	if !ok {
+		return exitUsage
+	}
+	if !validatePruneFlags(stderr, *configPath, *pipelineID, *destinationID, *dryRun, *apply) {
+		return exitUsage
+	}
+
+	if _, err := app.Prune(ctx, app.PruneOptions{
+		ConfigPath:    *configPath,
+		PipelineID:    *pipelineID,
+		DestinationID: *destinationID,
+		DryRun:        *dryRun,
+		Stdout:        stdout,
+		OutputFormat:  format,
+	}); err != nil {
+		return fail(stderr, err)
+	}
+	return exitOK
+}
+
+func validatePruneFlags(stderr io.Writer, configPath, pipelineID, destinationID string, dryRun, apply bool) bool {
+	if configPath == "" {
+		fmt.Fprintf(stderr, "%s: prune requires --config\n", app.Name)
+		return false
+	}
+	if pipelineID == "" {
+		fmt.Fprintf(stderr, "%s: prune requires --pipeline\n", app.Name)
+		return false
+	}
+	if destinationID == "" {
+		fmt.Fprintf(stderr, "%s: prune requires --destination\n", app.Name)
+		return false
+	}
+	if dryRun == apply {
+		fmt.Fprintf(stderr, "%s: prune requires exactly one of --dry-run or --apply\n", app.Name)
+		return false
+	}
+	return true
+}
+
+func printPruneHelp(w io.Writer) {
+	fmt.Fprint(w, `Usage:
+  distributor prune --config <path> --pipeline <id> --destination <id> (--dry-run|--apply) [--format text|json]
+
+Options:
+  --config <path>       Path to config file
+  --pipeline <id>       Pipeline id that selects the destination root
+  --destination <id>    Destination id that selects the destination root
+  --dry-run             Report planned deletes without deleting outputs or rewriting state
+  --apply               Delete planned managed outputs and rewrite state
+  --format text|json    Output format
+
+Prune reads the selected destination's configured retention policy and managed
+state, then plans owner-scoped managed output deletion. --dry-run is read-only.
+--apply deletes only planned managed output paths, preserves unmanaged files,
+and rewrites state after confirmed deletes.
+`)
+}

internal/cli/prune_test.go

@@ -0,0 +1,210 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
+)
+
+func TestExecutePruneRejectsInvalidFlags(t *testing.T) {
+	tests := []struct {
+		name       string
+		args       []string
+		wantStderr string
+	}{
+		{
+			name:       "missing config",
+			args:       []string{"prune", "--pipeline", "reports", "--destination", "archive", "--dry-run"},
+			wantStderr: "requires --config",
+		},
+		{
+			name:       "missing pipeline",
+			args:       []string{"prune", "--config", "config.yml", "--destination", "archive", "--dry-run"},
+			wantStderr: "requires --pipeline",
+		},
+		{
+			name:       "missing destination",
+			args:       []string{"prune", "--config", "config.yml", "--pipeline", "reports", "--dry-run"},
+			wantStderr: "requires --destination",
+		},
+		{
+			name:       "missing mode",
+			args:       []string{"prune", "--config", "config.yml", "--pipeline", "reports", "--destination", "archive"},
+			wantStderr: "requires exactly one of --dry-run or --apply",
+		},
+		{
+			name:       "conflicting modes",
+			args:       []string{"prune", "--config", "config.yml", "--pipeline", "reports", "--destination", "archive", "--dry-run", "--apply"},
+			wantStderr: "requires exactly one of --dry-run or --apply",
+		},
+		{
+			name:       "invalid format",
+			args:       []string{"prune", "--config", "config.yml", "--pipeline", "reports", "--destination", "archive", "--dry-run", "--format", "xml"},
+			wantStderr: "format must be text or json",
+		},
+		{
+			name:       "positional",
+			args:       []string{"prune", "--config", "config.yml", "--pipeline", "reports", "--destination", "archive", "--dry-run", "extra"},
+			wantStderr: "does not accept positional arguments",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			code := Execute(context.Background(), tt.args, &stdout, &stderr)
+			if code != exitUsage {
+				t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitUsage, stderr.String())
+			}
+			if stdout.Len() != 0 {
+				t.Fatalf("stdout = %q, want empty", stdout.String())
+			}
+			if !strings.Contains(stderr.String(), tt.wantStderr) {
+				t.Fatalf("stderr = %q, want substring %q", stderr.String(), tt.wantStderr)
+			}
+		})
+	}
+}
+
+func TestExecutePruneDryRunReportsWithoutWriting(t *testing.T) {
+	destinationRoot, configPath := writePruneLocalFixture(t)
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{
+		"prune",
+		"--config", configPath,
+		"--pipeline", "reports",
+		"--destination", "archive",
+		"--dry-run",
+	}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	if output := stdout.String(); !strings.Contains(output, "status=would_change") || !strings.Contains(output, "planned=2") || !strings.Contains(output, "deleted=0") {
+		t.Fatalf("stdout = %q, want dry-run prune summary", output)
+	}
+	assertLocalFile(t, filepath.Join(destinationRoot, "report.md"), "# Report\nSunny.\n")
+	assertLocalFile(t, filepath.Join(destinationRoot, "summary.txt"), "Summary\n")
+	assertLocalFile(t, filepath.Join(destinationRoot, "extra.txt"), "unmanaged")
+	destinationState := testutil.ReadDestinationState(t, filepath.Join(destinationRoot, storage.StateFileName))
+	if got := strings.Join(state.ManagedOutputPaths(destinationState), ","); got != "report.md,summary.txt" {
+		t.Fatalf("state outputs = %q, want original outputs", got)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecutePruneJSONReport(t *testing.T) {
+	_, configPath := writePruneLocalFixture(t)
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{
+		"prune",
+		"--config", configPath,
+		"--pipeline", "reports",
+		"--destination", "archive",
+		"--dry-run",
+		"--format", "json",
+	}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	if envelope["command"] != "prune" || envelope["ok"] != true {
+		t.Fatalf("envelope = %#v, want prune ok", envelope)
+	}
+	result := envelopeResult(t, envelope)
+	if result["would_change"] != true || result["state_changed"] != false || result["dry_run"] != true {
+		t.Fatalf("result = %#v, want dry-run pending change", result)
+	}
+	planned, ok := result["planned_outputs"].([]any)
+	if !ok || len(planned) != 2 {
+		t.Fatalf("planned outputs = %#v, want two", result["planned_outputs"])
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecutePruneApplyDeletesManagedOutputs(t *testing.T) {
+	destinationRoot, configPath := writePruneLocalFixture(t)
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{
+		"prune",
+		"--config", configPath,
+		"--pipeline", "reports",
+		"--destination", "archive",
+		"--apply",
+	}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	if output := stdout.String(); !strings.Contains(output, "status=changed") || !strings.Contains(output, "deleted=2") {
+		t.Fatalf("stdout = %q, want applied prune summary", output)
+	}
+	if _, err := os.Stat(filepath.Join(destinationRoot, "report.md")); !os.IsNotExist(err) {
+		t.Fatalf("report.md stat error = %v, want not exist", err)
+	}
+	if _, err := os.Stat(filepath.Join(destinationRoot, "summary.txt")); !os.IsNotExist(err) {
+		t.Fatalf("summary.txt stat error = %v, want not exist", err)
+	}
+	assertLocalFile(t, filepath.Join(destinationRoot, "extra.txt"), "unmanaged")
+	if _, err := os.Stat(filepath.Join(destinationRoot, storage.StateFileName)); err != nil {
+		t.Fatalf("state file stat error = %v", err)
+	}
+	destinationState := testutil.ReadDestinationState(t, filepath.Join(destinationRoot, storage.StateFileName))
+	if got := state.ManagedOutputPaths(destinationState); len(got) != 0 {
+		t.Fatalf("state outputs = %#v, want none", got)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func writePruneLocalFixture(t *testing.T) (string, string) {
+	t.Helper()
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	manifest := testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+	testutil.WriteDestinationState(t, destinationRoot, "", manifest, testutil.DestinationStateOptions{})
+	for _, file := range testutil.DefaultSourceFiles() {
+		path := filepath.Join(destinationRoot, filepath.FromSlash(file.Path))
+		if err := os.WriteFile(path, []byte(file.Data), 0o600); err != nil {
+			t.Fatalf("write destination output: %v", err)
+		}
+	}
+	if err := os.WriteFile(filepath.Join(destinationRoot, "extra.txt"), []byte("unmanaged"), 0o600); err != nil {
+		t.Fatalf("write unmanaged output: %v", err)
+	}
+	configPath := filepath.Join(t.TempDir(), "config.yml")
+	config := `
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: ` + sourceRoot + `
+    destinations:
+      - id: archive
+        backend: local
+        path: ` + destinationRoot + `
+        retention:
+          prune:
+            enabled: true
+            older_than: 1h
+`
+	if err := os.WriteFile(configPath, []byte(strings.TrimSpace(config)+"\n"), 0o600); err != nil {
+		t.Fatalf("write prune config: %v", err)
+	}
+	return destinationRoot, configPath
+}

internal/cli/reconcile_state.go

@@ -0,0 +1,84 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/app"
+)
+
+func reconcileStateCommand(ctx context.Context, args []string, stdout, stderr io.Writer) int {
+	if hasHelp(args) {
+		printReconcileStateHelp(stdout)
+		return exitOK
+	}
+
+	flags := newFlagSet("reconcile-state", stderr)
+	configPath := flags.String("config", "", "path to config file")
+	pipelineID := flags.String("pipeline", "", "pipeline id")
+	destinationID := flags.String("destination", "", "destination id")
+	allOwners := flags.Bool("all-owners", false, "repair all shared-root owners in the selected destination root")
+	dryRun := flags.Bool("dry-run", false, "report repairs without rewriting state")
+	formatFlag := addFormatFlag(flags)
+	if err := flags.Parse(args); err != nil {
+		return exitUsage
+	}
+	if rejectPositionalArgs(stderr, "reconcile-state", flags.Args()) {
+		return exitUsage
+	}
+	format, ok := parseOutputFormat(stderr, "reconcile-state", *formatFlag)
+	if !ok {
+		return exitUsage
+	}
+	if !validateReconcileStateFlags(stderr, *configPath, *pipelineID, *destinationID) {
+		return exitUsage
+	}
+
+	if _, err := app.ReconcileState(ctx, app.ReconcileStateOptions{
+		ConfigPath:    *configPath,
+		PipelineID:    *pipelineID,
+		DestinationID: *destinationID,
+		AllOwners:     *allOwners,
+		DryRun:        *dryRun,
+		Stdout:        stdout,
+		OutputFormat:  format,
+	}); err != nil {
+		return fail(stderr, err)
+	}
+	return exitOK
+}
+
+func validateReconcileStateFlags(stderr io.Writer, configPath, pipelineID, destinationID string) bool {
+	if configPath == "" {
+		fmt.Fprintf(stderr, "%s: reconcile-state requires --config\n", app.Name)
+		return false
+	}
+	if pipelineID == "" {
+		fmt.Fprintf(stderr, "%s: reconcile-state requires --pipeline\n", app.Name)
+		return false
+	}
+	if destinationID == "" {
+		fmt.Fprintf(stderr, "%s: reconcile-state requires --destination\n", app.Name)
+		return false
+	}
+	return true
+}
+
+func printReconcileStateHelp(w io.Writer) {
+	fmt.Fprint(w, `Usage:
+  distributor reconcile-state --config <path> --pipeline <id> --destination <id> [--all-owners] [--dry-run] [--format text|json]
+
+Options:
+  --config <path>       Path to config file
+  --pipeline <id>       Pipeline id that selects the destination root
+  --destination <id>    Destination id that selects the destination root
+  --all-owners          Repair all shared-root owners in the selected destination root
+  --dry-run             Report repairs without rewriting state
+  --format text|json    Output format
+
+Reconcile-state checks managed output records against destination storage and
+removes records for missing managed outputs unless --dry-run is set. It reports
+unmanaged entries but does not delete or adopt destination files.
+`)
+}

internal/cli/reconcile_state_test.go

@@ -0,0 +1,190 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
+)
+
+func TestExecuteReconcileStateAppliesByDefault(t *testing.T) {
+	_, destinationRoot, configPath := writeReconcileStateLocalFixture(t)
+	if err := os.WriteFile(filepath.Join(destinationRoot, "report.md"), []byte("# Report\nSunny.\n"), 0o600); err != nil {
+		t.Fatalf("write managed output: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(destinationRoot, "extra.txt"), []byte("unmanaged"), 0o600); err != nil {
+		t.Fatalf("write unmanaged output: %v", err)
+	}
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{
+		"reconcile-state",
+		"--config", configPath,
+		"--pipeline", "reports",
+		"--destination", "archive",
+	}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "status=changed") {
+		t.Fatalf("stdout = %q, want changed status", stdout.String())
+	}
+	destinationState := testutil.ReadDestinationState(t, filepath.Join(destinationRoot, storage.StateFileName))
+	if got := strings.Join(state.ManagedOutputPaths(destinationState), ","); got != "report.md" {
+		t.Fatalf("state outputs = %q, want report.md", got)
+	}
+	assertLocalFile(t, filepath.Join(destinationRoot, "extra.txt"), "unmanaged")
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecuteReconcileStateDryRunReportsWithoutWriting(t *testing.T) {
+	_, destinationRoot, configPath := writeReconcileStateLocalFixture(t)
+	if err := os.WriteFile(filepath.Join(destinationRoot, "report.md"), []byte("# Report\nSunny.\n"), 0o600); err != nil {
+		t.Fatalf("write managed output: %v", err)
+	}
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{
+		"reconcile-state",
+		"--config", configPath,
+		"--pipeline", "reports",
+		"--destination", "archive",
+		"--dry-run",
+	}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "status=would_change") {
+		t.Fatalf("stdout = %q, want would_change status", stdout.String())
+	}
+	destinationState := testutil.ReadDestinationState(t, filepath.Join(destinationRoot, storage.StateFileName))
+	if got := strings.Join(state.ManagedOutputPaths(destinationState), ","); got != "report.md,summary.txt" {
+		t.Fatalf("state outputs = %q, want original outputs", got)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecuteReconcileStateJSONReport(t *testing.T) {
+	_, destinationRoot, configPath := writeReconcileStateLocalFixture(t)
+	if err := os.WriteFile(filepath.Join(destinationRoot, "report.md"), []byte("# Report\nSunny.\n"), 0o600); err != nil {
+		t.Fatalf("write managed output: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(destinationRoot, "extra.txt"), []byte("unmanaged"), 0o600); err != nil {
+		t.Fatalf("write unmanaged output: %v", err)
+	}
+	var stdout, stderr bytes.Buffer
+
+	code := Execute(context.Background(), []string{
+		"reconcile-state",
+		"--config", configPath,
+		"--pipeline", "reports",
+		"--destination", "archive",
+		"--dry-run",
+		"--format", "json",
+	}, &stdout, &stderr)
+
+	if code != exitOK {
+		t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitOK, stderr.String())
+	}
+	envelope := decodeEnvelope(t, &stdout)
+	if envelope["command"] != "reconcile-state" || envelope["ok"] != true {
+		t.Fatalf("envelope = %#v, want reconcile-state ok", envelope)
+	}
+	result := envelopeResult(t, envelope)
+	if result["would_change"] != true || result["changed"] != false || result["dry_run"] != true {
+		t.Fatalf("result = %#v, want dry-run pending change", result)
+	}
+	missing, ok := result["missing_managed_outputs"].([]any)
+	if !ok || len(missing) != 1 {
+		t.Fatalf("missing outputs = %#v, want one", result["missing_managed_outputs"])
+	}
+	unmanaged, ok := result["unmanaged_entries"].([]any)
+	if !ok || len(unmanaged) != 1 {
+		t.Fatalf("unmanaged entries = %#v, want one", result["unmanaged_entries"])
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestExecuteReconcileStateRejectsInvalidFlags(t *testing.T) {
+	tests := []struct {
+		name       string
+		args       []string
+		wantStderr string
+	}{
+		{
+			name:       "missing config",
+			args:       []string{"reconcile-state", "--pipeline", "reports", "--destination", "archive"},
+			wantStderr: "requires --config",
+		},
+		{
+			name:       "missing pipeline",
+			args:       []string{"reconcile-state", "--config", "config.yml", "--destination", "archive"},
+			wantStderr: "requires --pipeline",
+		},
+		{
+			name:       "missing destination",
+			args:       []string{"reconcile-state", "--config", "config.yml", "--pipeline", "reports"},
+			wantStderr: "requires --destination",
+		},
+		{
+			name:       "invalid format",
+			args:       []string{"reconcile-state", "--config", "config.yml", "--pipeline", "reports", "--destination", "archive", "--format", "xml"},
+			wantStderr: "format must be text or json",
+		},
+		{
+			name:       "positional",
+			args:       []string{"reconcile-state", "--config", "config.yml", "--pipeline", "reports", "--destination", "archive", "extra"},
+			wantStderr: "does not accept positional arguments",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			code := Execute(context.Background(), tt.args, &stdout, &stderr)
+			if code != exitUsage {
+				t.Fatalf("exit code = %d, want %d; stderr = %q", code, exitUsage, stderr.String())
+			}
+			if stdout.Len() != 0 {
+				t.Fatalf("stdout = %q, want empty", stdout.String())
+			}
+			if !strings.Contains(stderr.String(), tt.wantStderr) {
+				t.Fatalf("stderr = %q, want substring %q", stderr.String(), tt.wantStderr)
+			}
+		})
+	}
+}
+
+func writeReconcileStateLocalFixture(t *testing.T) (string, string, string) {
+	t.Helper()
+	sourceRoot := t.TempDir()
+	destinationRoot := t.TempDir()
+	manifest := testutil.WriteSourceBundle(t, sourceRoot, "", testutil.BundleOptions{})
+	testutil.WriteDestinationState(t, destinationRoot, "", manifest, testutil.DestinationStateOptions{})
+	configPath := testutil.WriteMinimalLocalConfig(t, sourceRoot, destinationRoot)
+	return sourceRoot, destinationRoot, configPath
+}
+
+func assertLocalFile(t *testing.T, path, want string) {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read file %s: %v", path, err)
+	}
+	if string(data) != want {
+		t.Fatalf("file %s = %q, want %q", path, data, want)
+	}
+}

internal/cli/root.go

@@ -29,6 +29,10 @@ func Execute(ctx context.Context, args []string, stdout, stderr io.Writer) int {
 		return versionCommand(ctx, args[1:], stdout, stderr)
 	case "run":
 		return runCommand(ctx, args[1:], stdout, stderr)
+	case "reconcile-state":
+		return reconcileStateCommand(ctx, args[1:], stdout, stderr)
+	case "prune":
+		return pruneCommand(ctx, args[1:], stdout, stderr)
 	case "serve":
 		return serveCommand(ctx, args[1:], stdout, stderr)
 	case "validate":
@@ -53,6 +57,9 @@ Usage:
 Commands:
   version    Print version information
   run        Run configured distribution pipelines
+  reconcile-state
+             Repair missing managed-output records in destination state
+  prune      Prune managed outputs using configured retention policy
   serve      Run the HTTP upload server
   validate   Validate a source bundle or bundle tree
   inspect    Inspect bundles or distributor state

internal/config/config.go

@@ -38,24 +38,27 @@ type Pipeline struct {
 }
 
 type Destination struct {
-	ID        string         `yaml:"id"`
+	ID             string               `yaml:"id"`
-	Backend   string         `yaml:"backend"`
+	Backend        string               `yaml:"backend"`
-	Host      string         `yaml:"host"`
+	Host           string               `yaml:"host"`
-	User      string         `yaml:"user"`
+	User           string               `yaml:"user"`
-	Port      int            `yaml:"port"`
+	Port           int                  `yaml:"port"`
-	Path      string         `yaml:"path"`
+	Path           string               `yaml:"path"`
-	Endpoint  string         `yaml:"endpoint"`
+	Endpoint       string               `yaml:"endpoint"`
-	Bucket    string         `yaml:"bucket"`
+	Bucket         string               `yaml:"bucket"`
-	Prefix    string         `yaml:"prefix"`
+	Prefix         string               `yaml:"prefix"`
-	Region    string         `yaml:"region"`
+	Region         string               `yaml:"region"`
-	ForcePath *bool          `yaml:"force_path_style"`
+	ForcePath      *bool                `yaml:"force_path_style"`
-	Creds     Credentials    `yaml:"credentials"`
+	Creds          Credentials          `yaml:"credentials"`
-	SSH       SSH            `yaml:",inline"`
+	SSH            SSH                  `yaml:",inline"`
-	Publish   *PublishPolicy `yaml:"publish"`
+	Publish        *PublishPolicy       `yaml:"publish"`
-	Transform Transform      `yaml:"transform"`
+	Transform      Transform            `yaml:"transform"`
-	PathMap   PathMapping    `yaml:"path_mapping"`
+	PathMap        PathMapping          `yaml:"path_mapping"`
-	Links     *Links         `yaml:"links"`
+	Links          *Links               `yaml:"links"`
-	Transfer  TransferPolicy `yaml:"transfer"`
+	State          StatePolicy          `yaml:"state"`
+	Reconciliation ReconciliationPolicy `yaml:"reconciliation"`
+	Retention      RetentionPolicy      `yaml:"retention"`
+	Transfer       TransferPolicy       `yaml:"transfer"`
 }
 
 type Backend struct {
@@ -118,6 +121,24 @@ type Links struct {
 	Primary string `yaml:"primary"`
 }
 
+type ReconciliationPolicy struct {
+	Mode string `yaml:"mode"`
+}
+
+type StatePolicy struct {
+	Mode string `yaml:"mode"`
+}
+
+type RetentionPolicy struct {
+	Prune PrunePolicy `yaml:"prune"`
+}
+
+type PrunePolicy struct {
+	Enabled    bool      `yaml:"enabled"`
+	OlderThan  *Duration `yaml:"older_than"`
+	KeepLatest *int      `yaml:"keep_latest"`
+}
+
 type TransferPolicy struct {
 	OnDestinationSame  string `yaml:"on_destination_same"`
 	OnDestinationOlder string `yaml:"on_destination_older"`

internal/config/defaults.go

@@ -42,6 +42,16 @@ const (
 	LinkPrimarySource = "source"
 )
 
+const (
+	ReconciliationModeReplace = "replace"
+	ReconciliationModeMerge   = "merge"
+)
+
+const (
+	StateModeSingleOwner = "single_owner"
+	StateModeSharedRoot  = "shared_root"
+)
+
 const DefaultS3Region = "us-east-1"
 
 const (
@@ -79,6 +89,12 @@ func ApplyDefaults(cfg *Config) {
 			if destination.Links != nil && destination.Links.Primary == "" {
 				destination.Links.Primary = LinkPrimaryAuto
 			}
+			if destination.State.Mode == "" {
+				destination.State.Mode = StateModeSingleOwner
+			}
+			if destination.Reconciliation.Mode == "" {
+				destination.Reconciliation.Mode = ReconciliationModeReplace
+			}
 			if destination.Transfer.OnDestinationSame == "" {
 				destination.Transfer.OnDestinationSame = TransferActionSkip
 			}

internal/config/load_test.go

@@ -33,6 +33,15 @@ pipelines:
 	if got, want := destination.Transfer.OnDestinationOlder, TransferActionReplace; got != want {
 		t.Fatalf("transfer default = %q, want %q", got, want)
 	}
+	if got, want := destination.Reconciliation.Mode, ReconciliationModeReplace; got != want {
+		t.Fatalf("reconciliation mode default = %q, want %q", got, want)
+	}
+	if got, want := destination.State.Mode, StateModeSingleOwner; got != want {
+		t.Fatalf("state mode default = %q, want %q", got, want)
+	}
+	if destination.Retention.Prune.Enabled {
+		t.Fatal("retention.prune.enabled default = true, want false")
+	}
 	if cfg.Secrets.Directory != "" {
 		t.Fatalf("secrets.directory = %q, want empty", cfg.Secrets.Directory)
 	}
@@ -164,6 +173,94 @@ pipelines:
 	}
 }
 
+func TestLoadFileAcceptsExplicitReconciliationModes(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: /source
+    destinations:
+      - id: archive
+        backend: local
+        path: /archive
+        reconciliation:
+          mode: replace
+      - id: web
+        backend: local
+        path: /web
+        reconciliation:
+          mode: merge
+`)
+
+	destinations := cfg.Pipelines[0].Destinations
+	if got, want := destinations[0].Reconciliation.Mode, ReconciliationModeReplace; got != want {
+		t.Fatalf("archive reconciliation mode = %q, want %q", got, want)
+	}
+	if got, want := destinations[1].Reconciliation.Mode, ReconciliationModeMerge; got != want {
+		t.Fatalf("web reconciliation mode = %q, want %q", got, want)
+	}
+}
+
+func TestLoadFileAcceptsExplicitStateModes(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: /source
+    destinations:
+      - id: archive
+        backend: local
+        path: /archive
+        state:
+          mode: single_owner
+      - id: web
+        backend: local
+        path: /web
+        state:
+          mode: shared_root
+`)
+
+	destinations := cfg.Pipelines[0].Destinations
+	if got, want := destinations[0].State.Mode, StateModeSingleOwner; got != want {
+		t.Fatalf("archive state mode = %q, want %q", got, want)
+	}
+	if got, want := destinations[1].State.Mode, StateModeSharedRoot; got != want {
+		t.Fatalf("web state mode = %q, want %q", got, want)
+	}
+}
+
+func TestLoadFileAcceptsRetentionPruneConfig(t *testing.T) {
+	cfg := loadConfig(t, `
+pipelines:
+  - id: reports
+    source:
+      backend: local
+      path: /source
+    destinations:
+      - id: archive
+        backend: local
+        path: /archive
+        retention:
+          prune:
+            enabled: true
+            older_than: 168h
+            keep_latest: 3
+`)
+
+	prune := cfg.Pipelines[0].Destinations[0].Retention.Prune
+	if !prune.Enabled {
+		t.Fatal("retention.prune.enabled = false, want true")
+	}
+	if prune.OlderThan == nil || prune.OlderThan.String() != "168h0m0s" {
+		t.Fatalf("retention.prune.older_than = %v, want 168h", prune.OlderThan)
+	}
+	if prune.KeepLatest == nil || *prune.KeepLatest != 3 {
+		t.Fatalf("retention.prune.keep_latest = %v, want 3", prune.KeepLatest)
+	}
+}
+
 func TestLoadFileAcceptsFixedPathMapping(t *testing.T) {
 	cfg := loadConfig(t, `
 pipelines:
@@ -641,6 +738,7 @@ pipelines: [{id: reports, source: {backend: http_upload, max_upload_size: 20XB},
 pipelines: [{id: reports, source: {backend: http_upload, max_upload_size: 0B}, destinations: [{id: archive, backend: local, path: /archive}]}]`,
 		"server duration":         `server: {http: {retention: forever}}`,
 		"zero server duration":    `server: {http: {retention: 0s}}`,
+		"prune duration":          `pipelines: [{id: reports, source: {backend: local, path: /source}, destinations: [{id: archive, backend: local, path: /archive, retention: {prune: {enabled: true, older_than: forever}}}]}]`,
 		"missing upload tokens":   `pipelines: [{id: reports, source: {backend: http_upload}, destinations: [{id: archive, backend: local, path: /archive}]}]`,
 		"destination http upload": `pipelines: [{id: reports, source: {backend: local, path: /source}, destinations: [{id: ingest, backend: http_upload}]}]`,
 		"literal token": `upload_tokens: [{id: reporter, token: secret, token_env: UPLOAD_TOKEN, allow_pipelines: [reports]}]
@@ -843,6 +941,8 @@ func TestExampleConfigsLoad(t *testing.T) {
 		"../../examples/local-index.yml",
 		"../../examples/fan-out.yml",
 		"../../examples/archive-and-latest.yml",
+		"../../examples/merge-reconciliation.yml",
+		"../../examples/shared-root.yml",
 		"../../examples/http-upload-local.yml",
 		"../../examples/ssh-destination.yml",
 		"../../examples/s3-destination.yml",

internal/config/validate.go

@@ -72,6 +72,9 @@ func Validate(cfg Config) error {
 			errs = validatePublishTransformPolicy(errs, destinationContext, destination.Publish, destination.Transform)
 			errs = validatePathMapping(errs, destinationContext+".path_mapping", destination.PathMap)
 			errs = validateLinks(errs, destinationContext+".links", destination.Links)
+			errs = validateStatePolicy(errs, destinationContext+".state", destination.State)
+			errs = validateReconciliationPolicy(errs, destinationContext+".reconciliation", destination.Reconciliation)
+			errs = validateRetentionPolicy(errs, destinationContext+".retention", destination.Retention)
 			errs = validateTransferPolicy(errs, destinationContext+".transfer", destination.Transfer)
 		}
 	}
@@ -314,6 +317,37 @@ func validateLinks(errs ValidationErrors, context string, links *Links) Validati
 	return errs
 }
 
+func validateReconciliationPolicy(errs ValidationErrors, context string, policy ReconciliationPolicy) ValidationErrors {
+	if policy.Mode != ReconciliationModeReplace && policy.Mode != ReconciliationModeMerge {
+		errs = append(errs, context+".mode must be "+ReconciliationModeReplace+" or "+ReconciliationModeMerge)
+	}
+	return errs
+}
+
+func validateRetentionPolicy(errs ValidationErrors, context string, policy RetentionPolicy) ValidationErrors {
+	prune := policy.Prune
+	if !prune.Enabled {
+		return errs
+	}
+	if prune.OlderThan == nil && prune.KeepLatest == nil {
+		errs = append(errs, context+".prune must set older_than or keep_latest when enabled is true")
+	}
+	if prune.OlderThan != nil && *prune.OlderThan <= 0 {
+		errs = append(errs, context+".prune.older_than must be greater than zero")
+	}
+	if prune.KeepLatest != nil && *prune.KeepLatest < 0 {
+		errs = append(errs, context+".prune.keep_latest must be zero or greater")
+	}
+	return errs
+}
+
+func validateStatePolicy(errs ValidationErrors, context string, policy StatePolicy) ValidationErrors {
+	if policy.Mode != StateModeSingleOwner && policy.Mode != StateModeSharedRoot {
+		errs = append(errs, context+".mode must be "+StateModeSingleOwner+" or "+StateModeSharedRoot)
+	}
+	return errs
+}
+
 func validateTransferPolicy(errs ValidationErrors, context string, policy TransferPolicy) ValidationErrors {
 	if policy.OnDestinationSame != TransferActionSkip && policy.OnDestinationSame != TransferActionFail {
 		errs = append(errs, context+".on_destination_same must be skip or fail")

internal/config/validate_test.go

@@ -3,6 +3,7 @@ package config
 import (
 	"strings"
 	"testing"
+	"time"
 )
 
 func TestValidatePublishTransformPolicy(t *testing.T) {
@@ -107,6 +108,118 @@ func TestValidatePathMapping(t *testing.T) {
 	}
 }
 
+func TestValidateReconciliationPolicy(t *testing.T) {
+	tests := []struct {
+		name    string
+		mode    string
+		wantErr bool
+	}{
+		{name: "replace", mode: ReconciliationModeReplace},
+		{name: "merge", mode: ReconciliationModeMerge},
+		{name: "invalid", mode: "append", wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := Config{Pipelines: []Pipeline{{
+				ID:     "reports",
+				Source: Backend{Backend: BackendLocal, Path: "/source"},
+				Destinations: []Destination{{
+					ID:             "archive",
+					Backend:        BackendLocal,
+					Path:           "/destination",
+					Reconciliation: ReconciliationPolicy{Mode: tt.mode},
+				}},
+			}}}
+			ApplyDefaults(&cfg)
+			err := Validate(cfg)
+			if tt.wantErr && err == nil {
+				t.Fatal("Validate() error = nil, want error")
+			}
+			if !tt.wantErr && err != nil {
+				t.Fatalf("Validate() error = %v", err)
+			}
+		})
+	}
+}
+
+func TestValidateStatePolicy(t *testing.T) {
+	tests := []struct {
+		name    string
+		mode    string
+		wantErr bool
+	}{
+		{name: "single owner", mode: StateModeSingleOwner},
+		{name: "shared root", mode: StateModeSharedRoot},
+		{name: "invalid", mode: "shared", wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := Config{Pipelines: []Pipeline{{
+				ID:     "reports",
+				Source: Backend{Backend: BackendLocal, Path: "/source"},
+				Destinations: []Destination{{
+					ID:      "archive",
+					Backend: BackendLocal,
+					Path:    "/destination",
+					State:   StatePolicy{Mode: tt.mode},
+				}},
+			}}}
+			ApplyDefaults(&cfg)
+			err := Validate(cfg)
+			if tt.wantErr && err == nil {
+				t.Fatal("Validate() error = nil, want error")
+			}
+			if !tt.wantErr && err != nil {
+				t.Fatalf("Validate() error = %v", err)
+			}
+		})
+	}
+}
+
+func TestValidateRetentionPolicy(t *testing.T) {
+	olderThan := Duration(24 * time.Hour)
+	zeroDuration := Duration(0)
+	keepZero := 0
+	keepThree := 3
+	keepNegative := -1
+	tests := []struct {
+		name      string
+		retention RetentionPolicy
+		wantErr   bool
+	}{
+		{name: "disabled"},
+		{name: "older than", retention: RetentionPolicy{Prune: PrunePolicy{Enabled: true, OlderThan: &olderThan}}},
+		{name: "keep zero", retention: RetentionPolicy{Prune: PrunePolicy{Enabled: true, KeepLatest: &keepZero}}},
+		{name: "keep latest", retention: RetentionPolicy{Prune: PrunePolicy{Enabled: true, KeepLatest: &keepThree}}},
+		{name: "combined", retention: RetentionPolicy{Prune: PrunePolicy{Enabled: true, OlderThan: &olderThan, KeepLatest: &keepThree}}},
+		{name: "missing policy", retention: RetentionPolicy{Prune: PrunePolicy{Enabled: true}}, wantErr: true},
+		{name: "zero older than", retention: RetentionPolicy{Prune: PrunePolicy{Enabled: true, OlderThan: &zeroDuration}}, wantErr: true},
+		{name: "negative keep latest", retention: RetentionPolicy{Prune: PrunePolicy{Enabled: true, KeepLatest: &keepNegative}}, wantErr: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := Config{Pipelines: []Pipeline{{
+				ID:     "reports",
+				Source: Backend{Backend: BackendLocal, Path: "/source"},
+				Destinations: []Destination{{
+					ID:        "archive",
+					Backend:   BackendLocal,
+					Path:      "/destination",
+					Retention: tt.retention,
+				}},
+			}}}
+			ApplyDefaults(&cfg)
+			err := Validate(cfg)
+			if tt.wantErr && err == nil {
+				t.Fatal("Validate() error = nil, want error")
+			}
+			if !tt.wantErr && err != nil {
+				t.Fatalf("Validate() error = %v", err)
+			}
+		})
+	}
+}
+
 func TestValidateLinks(t *testing.T) {
 	tests := []struct {
 		name    string

internal/publish/execute.go

@@ -6,15 +6,20 @@ import (
 	"fmt"
 	"time"
 
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
 	"gitea.maximumdirect.net/eric/distributor/internal/state"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 )
 
 func Execute(ctx context.Context, req Request, plan Plan) error {
+	plan.Reconciliation = normalizeReconciliation(plan.Reconciliation)
 	switch plan.Action {
 	case ActionSkipSame, ActionSkipDestinationNewer:
 		return nil
 	case ActionPublishNew, ActionReplaceOlder, ActionForceReplace:
+		if usesSharedRootState(req, plan) {
+			return executeSharedRoot(ctx, req, plan)
+		}
 	default:
 		return fmt.Errorf("cannot execute action %s: %s", plan.Action, plan.Reason)
 	}
@@ -23,11 +28,13 @@ func Execute(ctx context.Context, req Request, plan Plan) error {
 		if plan.ExistingState == nil {
 			return fmt.Errorf("replace requires existing destination state")
 		}
-		if err := req.DestinationBackend.DeleteManagedBundle(ctx, req.DestinationBundlePath, stateOutputManagedPaths(plan.ExistingState.Outputs), storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true}); err != nil {
+		if plan.Reconciliation.Mode == config.ReconciliationModeReplace {
-			return err
+			if err := req.DestinationBackend.DeleteManagedBundle(ctx, req.DestinationBundlePath, state.ManagedOutputPaths(*plan.ExistingState), storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true}); err != nil {
-		}
+				return err
-		if err := ensureDestinationEmpty(ctx, req.DestinationBackend, req.DestinationBundlePath); err != nil {
+			}
-			return err
+			if err := ensureDestinationEmpty(ctx, req.DestinationBackend, req.DestinationBundlePath); err != nil {
+				return err
+			}
 		}
 	}
 	if plan.Action == ActionForceReplace {
@@ -38,10 +45,20 @@ func Execute(ctx context.Context, req Request, plan Plan) error {
 			return err
 		}
 	}
+	if usesMergeRetention(plan) {
+		if err := ensureMergeOutputPaths(ctx, req.DestinationBackend, req.DestinationBundlePath, plan); err != nil {
+			return err
+		}
+	}
 
 	writtenOutputs := make([]Output, 0, len(plan.Outputs))
+	newOutputs := make([]Output, 0, len(plan.Outputs))
 	cleanup := func() {
-		_ = req.DestinationBackend.DeleteManagedBundle(ctx, req.DestinationBundlePath, ManagedOutputPaths(writtenOutputs), storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true})
+		outputs := writtenOutputs
+		if usesMergeRetention(plan) {
+			outputs = newOutputs
+		}
+		_ = req.DestinationBackend.DeleteManagedBundle(ctx, req.DestinationBundlePath, ManagedOutputPaths(outputs), storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true})
 	}
 	for _, output := range plan.Outputs {
 		destinationPath, err := storage.Join(req.DestinationBundlePath, output.DestinationPath)
@@ -62,21 +79,39 @@ func Execute(ctx context.Context, req Request, plan Plan) error {
 				return err
 			}
 		}
-		if _, err := req.DestinationBackend.WriteFile(ctx, destinationPath, data, storage.WriteOptions{Overwrite: false, PreferAtomic: true}); err != nil {
+		managed := outputManagedByExistingState(output, plan.ExistingState)
+		if _, err := req.DestinationBackend.WriteFile(ctx, destinationPath, data, storage.WriteOptions{Overwrite: managed && usesMergeRetention(plan), PreferAtomic: true}); err != nil {
 			cleanup()
 			return err
 		}
 		writtenOutputs = append(writtenOutputs, output)
+		if !managed {
+			newOutputs = append(newOutputs, output)
+		}
 	}
 
+	now := time.Now().UTC()
+	createdAt := now
+	if plan.ExistingState != nil {
+		createdAt = plan.ExistingState.CreatedAt
+	}
+	stateOutputs, err := stateOutputsForPlan(plan, now)
+	if err != nil {
+		cleanup()
+		return err
+	}
 	destinationState := state.DistributorState{
 		SchemaVersion:      state.SchemaVersion,
 		DistributorVersion: req.DistributorVersion,
 		PipelineID:         req.PipelineID,
 		DestinationID:      req.DestinationID,
-		PublishedAt:        time.Now().UTC(),
+		PublishedAt:        now,
+		CreatedAt:          createdAt,
+		UpdatedAt:          now,
+		State:              state.StatePolicy{Mode: state.StateModeSingleOwner},
+		Reconciliation:     state.ReconciliationPolicy{Mode: plan.Reconciliation.Mode},
 		Source:             state.SourceState{Manifest: req.SourceBundle.Manifest},
-		Outputs:            StateOutputFiles(plan.Outputs),
+		Outputs:            stateOutputs,
 	}
 	if plan.PrimaryURL != "" {
 		destinationState.Links = &state.LinkState{PrimaryURL: plan.PrimaryURL}
@@ -96,9 +131,248 @@ func Execute(ctx context.Context, req Request, plan Plan) error {
 		cleanup()
 		return err
 	}
-	if _, err := req.DestinationBackend.WriteFile(ctx, statePath, data, storage.WriteOptions{Overwrite: false, PreferAtomic: true}); err != nil {
+	if _, err := req.DestinationBackend.WriteFile(ctx, statePath, data, storage.WriteOptions{Overwrite: plan.ExistingState != nil, PreferAtomic: true}); err != nil {
 		cleanup()
 		return err
 	}
 	return nil
 }
+
+func executeSharedRoot(ctx context.Context, req Request, plan Plan) error {
+	plan.Reconciliation = normalizeReconciliation(plan.Reconciliation)
+	if plan.Action == ActionForceReplace {
+		if err := req.DestinationBackend.DeletePrefix(ctx, req.DestinationBundlePath, storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true}); err != nil {
+			return err
+		}
+		if err := ensureDestinationEmpty(ctx, req.DestinationBackend, req.DestinationBundlePath); err != nil {
+			return err
+		}
+	}
+	if plan.Action == ActionReplaceOlder && plan.Reconciliation.Mode == config.ReconciliationModeReplace {
+		if err := req.DestinationBackend.DeleteManagedOutputs(ctx, req.DestinationBundlePath, sharedRootOutputPaths(plan.OwnerOutputsToDelete), storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true}); err != nil {
+			return err
+		}
+	}
+
+	writtenOutputs := make([]Output, 0, len(plan.Outputs))
+	newOutputs := make([]Output, 0, len(plan.Outputs))
+	cleanup := func() {
+		outputs := writtenOutputs
+		if plan.Reconciliation.Mode == config.ReconciliationModeMerge {
+			outputs = newOutputs
+		}
+		_ = req.DestinationBackend.DeleteManagedOutputs(ctx, req.DestinationBundlePath, ManagedOutputPaths(outputs), storage.DeleteOptions{IgnoreMissing: true, PruneEmptyDirs: true})
+	}
+	for _, output := range plan.Outputs {
+		destinationPath, err := storage.Join(req.DestinationBundlePath, output.DestinationPath)
+		if err != nil {
+			cleanup()
+			return err
+		}
+		data := output.Data
+		if output.Kind == state.OutputKindSource {
+			sourcePath, err := storage.Join(req.SourceBundle.RootRelativePath, output.SourcePath)
+			if err != nil {
+				cleanup()
+				return err
+			}
+			data, err = req.SourceBackend.ReadFile(ctx, sourcePath)
+			if err != nil {
+				cleanup()
+				return err
+			}
+		}
+		managed := outputManagedBySharedRootPlan(output, plan)
+		if _, err := req.DestinationBackend.WriteFile(ctx, destinationPath, data, storage.WriteOptions{Overwrite: managed, PreferAtomic: true}); err != nil {
+			cleanup()
+			return err
+		}
+		writtenOutputs = append(writtenOutputs, output)
+		if !managed {
+			newOutputs = append(newOutputs, output)
+		}
+	}
+
+	now := time.Now().UTC()
+	sharedRootState, err := sharedRootStateForPlan(req, plan, now)
+	if err != nil {
+		cleanup()
+		return err
+	}
+	if err := state.ValidateSharedRoot(sharedRootState); err != nil {
+		cleanup()
+		return err
+	}
+	data, err := json.MarshalIndent(sharedRootState, "", "  ")
+	if err != nil {
+		cleanup()
+		return err
+	}
+	data = append(data, '\n')
+	statePath, err := storage.StatePath(req.DestinationBundlePath)
+	if err != nil {
+		cleanup()
+		return err
+	}
+	if _, err := req.DestinationBackend.WriteFile(ctx, statePath, data, storage.WriteOptions{Overwrite: sharedRootStateWriteOverwrites(plan), PreferAtomic: true}); err != nil {
+		cleanup()
+		return err
+	}
+	return nil
+}
+
+func ensureMergeOutputPaths(ctx context.Context, backend storage.Backend, bundlePath string, plan Plan) error {
+	for _, output := range plan.Outputs {
+		if outputManagedByExistingState(output, plan.ExistingState) {
+			continue
+		}
+		destinationPath, err := storage.Join(bundlePath, output.DestinationPath)
+		if err != nil {
+			return err
+		}
+		if _, err := backend.Stat(ctx, destinationPath); err == nil {
+			return fmt.Errorf("merge output path %s exists but is not managed by destination state", storage.DisplayPath(output.DestinationPath))
+		} else if !storage.IsNotFound(err) {
+			return err
+		}
+	}
+	return nil
+}
+
+func usesSharedRootState(req Request, plan Plan) bool {
+	return normalizeState(req.State).Mode == config.StateModeSharedRoot || plan.StateMode == config.StateModeSharedRoot
+}
+
+func outputManagedByExistingState(output Output, existing *state.DistributorState) bool {
+	if existing == nil {
+		return false
+	}
+	_, ok := state.FindOutputByPath(existing.Outputs, output.DestinationPath)
+	return ok
+}
+
+func outputManagedBySharedRootPlan(output Output, plan Plan) bool {
+	for _, existing := range currentOwnerSharedRootOutputs(plan) {
+		if existing.Path == output.DestinationPath {
+			return true
+		}
+	}
+	return false
+}
+
+func stateOutputsForPlan(plan Plan, now time.Time) ([]state.OutputFile, error) {
+	existingOutputs := []state.OutputFile(nil)
+	if plan.ExistingState != nil {
+		existingOutputs = plan.ExistingState.Outputs
+	}
+	planned := state.ProjectOutputs(StateOutputProjections(plan.Outputs), existingOutputs, now)
+	if !usesMergeRetention(plan) || plan.ExistingState == nil {
+		return planned, nil
+	}
+	return state.MergeOutputFiles(plan.ExistingState.Outputs, planned)
+}
+
+func usesMergeRetention(plan Plan) bool {
+	return plan.Reconciliation.Mode == config.ReconciliationModeMerge && plan.Action == ActionReplaceOlder
+}
+
+func sharedRootStateForPlan(req Request, plan Plan, now time.Time) (state.SharedRootState, error) {
+	now = now.UTC()
+	scope := plan.OwnerScope
+	if scope.PipelineID == "" && scope.DestinationID == "" {
+		scope = state.CurrentOwnerScope(req.PipelineID, req.DestinationID)
+	}
+	base := sharedRootBaseState(req, plan, now)
+	owner := state.OwnerRecord{
+		Scope:          scope,
+		Reconciliation: state.ReconciliationPolicy{Mode: plan.Reconciliation.Mode},
+		Source:         state.SourceState{Manifest: req.SourceBundle.Manifest},
+	}
+	if plan.PrimaryURL != "" {
+		owner.Links = &state.LinkState{PrimaryURL: plan.PrimaryURL}
+	}
+	planned := state.ProjectSharedRootOutputs(StateOutputProjections(plan.Outputs), currentOwnerSharedRootOutputs(plan), scope, req.SourceBundle.Manifest, now)
+	if plan.Action == ActionReplaceOlder && plan.Reconciliation.Mode == config.ReconciliationModeMerge {
+		return state.MergeOwnerOutputs(base, scope, owner, planned)
+	}
+	return state.ReplaceOwnerOutputs(base, scope, owner, planned)
+}
+
+func sharedRootBaseState(req Request, plan Plan, now time.Time) state.SharedRootState {
+	if plan.Action == ActionForceReplace {
+		return newSharedRootState(req, now)
+	}
+	if plan.ExistingSharedRoot != nil {
+		base := *plan.ExistingSharedRoot
+		base.Owners = append([]state.OwnerRecord(nil), plan.ExistingSharedRoot.Owners...)
+		base.Outputs = append([]state.SharedRootOutputFile(nil), plan.ExistingSharedRoot.Outputs...)
+		base.DistributorVersion = req.DistributorVersion
+		base.UpdatedAt = now
+		return base
+	}
+	if plan.ExistingState != nil {
+		base := newSharedRootState(req, now)
+		base.CreatedAt = plan.ExistingState.CreatedAt
+		base.UpdatedAt = now
+		return base
+	}
+	return newSharedRootState(req, now)
+}
+
+func newSharedRootState(req Request, now time.Time) state.SharedRootState {
+	return state.SharedRootState{
+		SchemaVersion:      state.SharedRootSchemaVersion,
+		DistributorVersion: req.DistributorVersion,
+		CreatedAt:          now,
+		UpdatedAt:          now,
+		State:              state.StatePolicy{Mode: state.StateModeSharedRoot},
+		Owners:             []state.OwnerRecord{},
+		Outputs:            []state.SharedRootOutputFile{},
+	}
+}
+
+func currentOwnerSharedRootOutputs(plan Plan) []state.SharedRootOutputFile {
+	if plan.ExistingSharedRoot != nil {
+		outputs := make([]state.SharedRootOutputFile, 0, len(plan.ExistingSharedRoot.Outputs))
+		for _, output := range plan.ExistingSharedRoot.Outputs {
+			if output.Owner == plan.OwnerScope {
+				outputs = append(outputs, output)
+			}
+		}
+		return outputs
+	}
+	if plan.ExistingState != nil {
+		outputs := make([]state.SharedRootOutputFile, 0, len(plan.ExistingState.Outputs))
+		for _, output := range plan.ExistingState.Outputs {
+			outputs = append(outputs, state.SharedRootOutputFile{
+				Path:          output.Path,
+				Kind:          output.Kind,
+				SourcePath:    output.SourcePath,
+				Transform:     output.Transform,
+				URL:           output.URL,
+				SHA256:        output.SHA256,
+				Size:          output.Size,
+				Owner:         plan.OwnerScope,
+				SourceID:      plan.ExistingState.Source.Manifest.ID,
+				SourceDigest:  plan.ExistingState.Source.Manifest.Digest,
+				SourceCreated: plan.ExistingState.Source.Manifest.Created,
+				CreatedAt:     output.CreatedAt,
+				UpdatedAt:     output.UpdatedAt,
+			})
+		}
+		return outputs
+	}
+	return nil
+}
+
+func sharedRootOutputPaths(outputs []state.SharedRootOutputFile) []string {
+	paths := make([]string, 0, len(outputs))
+	for _, output := range outputs {
+		paths = append(paths, output.Path)
+	}
+	return paths
+}
+
+func sharedRootStateWriteOverwrites(plan Plan) bool {
+	return plan.ExistingSharedRoot != nil || plan.ExistingState != nil || plan.Action == ActionForceReplace
+}

internal/publish/execute_test.go

@@ -5,11 +5,15 @@ import (
 	"fmt"
 	"io"
 	"testing"
+	"time"
 
+	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
 	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage/fake"
 	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
+	"gitea.maximumdirect.net/eric/distributor/internal/transform"
 )
 
 func TestExecuteCleansUpAfterWriteFailure(t *testing.T) {
@@ -44,6 +48,250 @@ func TestExecuteCleansUpAfterWriteFailure(t *testing.T) {
 	}
 }
 
+func TestExecuteReplaceDeletesOmittedManagedOutputs(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\nNew.\n"}},
+	})
+	destinationBackend := fake.New()
+	older := sourceBundle.Manifest
+	older.Created = older.Created.Add(-time.Hour)
+	older.Files = append([]bundle.ManifestFile(nil), testutil.ValidManifest(testutil.BundleOptions{}).Files...)
+	older.Digest = bundle.BundleDigest(older.Files)
+	testutil.WriteFakeDestinationState(t, destinationBackend, "", older, testutil.DestinationStateOptions{})
+
+	req := testRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeReplace)
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	if plan.Action != ActionReplaceOlder {
+		t.Fatalf("plan action = %s, want replace_older", plan.Action)
+	}
+	if err := Execute(context.Background(), req, plan); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	testutil.AssertFakeFile(t, destinationBackend, "report.md", "# Report\nNew.\n")
+	testutil.AssertFakeMissing(t, destinationBackend, "summary.txt")
+	destinationState := readFakeState(t, destinationBackend, "")
+	if got, want := len(destinationState.Outputs), 1; got != want {
+		t.Fatalf("state output count = %d, want %d", got, want)
+	}
+	if got, want := destinationState.Reconciliation.Mode, config.ReconciliationModeReplace; got != want {
+		t.Fatalf("reconciliation mode = %q, want %q", got, want)
+	}
+}
+
+func TestExecuteMergeRetainsOmittedAndOverwritesManagedOutputs(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\nNew.\n"}},
+	})
+	destinationBackend := fake.New()
+	older := sourceBundle.Manifest
+	older.Created = older.Created.Add(-time.Hour)
+	older.Files = append([]bundle.ManifestFile(nil), testutil.ValidManifest(testutil.BundleOptions{}).Files...)
+	older.Digest = bundle.BundleDigest(older.Files)
+	existingState := testutil.WriteFakeDestinationState(t, destinationBackend, "", older, testutil.DestinationStateOptions{})
+
+	req := testRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeMerge)
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	if err := Execute(context.Background(), req, plan); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	testutil.AssertFakeFile(t, destinationBackend, "report.md", "# Report\nNew.\n")
+	testutil.AssertFakeFile(t, destinationBackend, "summary.txt", "old")
+	destinationState := readFakeState(t, destinationBackend, "")
+	outputs := outputsByPath(destinationState.Outputs)
+	if got, want := len(outputs), 2; got != want {
+		t.Fatalf("state output count = %d, want %d", got, want)
+	}
+	if !outputs["summary.txt"].CreatedAt.Equal(existingState.Outputs[1].CreatedAt) || !outputs["summary.txt"].UpdatedAt.Equal(existingState.Outputs[1].UpdatedAt) {
+		t.Fatalf("retained output timestamps = %#v, want existing %#v", outputs["summary.txt"], existingState.Outputs[1])
+	}
+	if !outputs["report.md"].CreatedAt.Equal(existingState.Outputs[0].CreatedAt) || !outputs["report.md"].UpdatedAt.After(existingState.Outputs[0].UpdatedAt) {
+		t.Fatalf("updated output timestamps = %#v, want preserved created_at and newer updated_at", outputs["report.md"])
+	}
+	if got, want := destinationState.Reconciliation.Mode, config.ReconciliationModeMerge; got != want {
+		t.Fatalf("reconciliation mode = %q, want %q", got, want)
+	}
+}
+
+func TestExecuteMergeFailsOnUnmanagedDestinationPathCollision(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\nNew.\n"}},
+	})
+	destinationBackend := fake.New()
+	older := sourceBundle.Manifest
+	older.Created = older.Created.Add(-time.Hour)
+	older.Files = []bundle.ManifestFile{{
+		Path:   "summary.txt",
+		SHA256: bundle.FileDigest([]byte("Summary\n")),
+		Size:   int64(len("Summary\n")),
+	}}
+	older.Digest = bundle.BundleDigest(older.Files)
+	testutil.WriteFakeDestinationState(t, destinationBackend, "", older, testutil.DestinationStateOptions{})
+	testutil.WriteFakeFile(t, destinationBackend, "report.md", "unmanaged")
+
+	req := testRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeMerge)
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	err = Execute(context.Background(), req, plan)
+	if err == nil {
+		t.Fatal("Execute() error = nil, want unmanaged path collision")
+	}
+	testutil.AssertFakeFile(t, destinationBackend, "report.md", "unmanaged")
+	testutil.AssertFakeFile(t, destinationBackend, "summary.txt", "old")
+}
+
+func TestExecuteMergeFailureCleansUpOnlyNewOutputs(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "", testutil.BundleOptions{
+		Files: []testutil.SourceFile{
+			{Path: "report.md", Data: "# Report\nNew.\n"},
+			{Path: "new.md", Data: "new\n"},
+			{Path: "fail.md", Data: "fail\n"},
+		},
+	})
+	destinationBackend := &failingBackend{Backend: fake.New(), failPath: "fail.md"}
+	older := sourceBundle.Manifest
+	older.Created = older.Created.Add(-time.Hour)
+	older.Files = []bundle.ManifestFile{sourceBundle.Manifest.Files[0]}
+	older.Digest = bundle.BundleDigest(older.Files)
+	testutil.WriteFakeDestinationState(t, destinationBackend.Backend, "", older, testutil.DestinationStateOptions{})
+
+	req := testRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeMerge)
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	err = Execute(context.Background(), req, plan)
+	if err == nil {
+		t.Fatal("Execute() error = nil, want injected failure")
+	}
+	testutil.AssertFakeFile(t, destinationBackend.Backend, "report.md", "# Report\nNew.\n")
+	testutil.AssertFakeMissing(t, destinationBackend.Backend, "new.md")
+	testutil.AssertFakeMissing(t, destinationBackend.Backend, "fail.md")
+}
+
+func TestExecuteFixedPathSupportsReconciliationModes(t *testing.T) {
+	for _, mode := range []string{config.ReconciliationModeReplace, config.ReconciliationModeMerge} {
+		t.Run(mode, func(t *testing.T) {
+			sourceBackend := fake.New()
+			sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "new", testutil.BundleOptions{
+				Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\nNew.\n"}},
+			})
+			destinationBackend := fake.New()
+			older := sourceBundle.Manifest
+			older.ID = "older.source"
+			older.Created = older.Created.Add(-time.Hour)
+			testutil.WriteFakeDestinationState(t, destinationBackend, "", older, testutil.DestinationStateOptions{})
+
+			req := testRequest(sourceBackend, destinationBackend, sourceBundle, mode)
+			req.DestinationBundlePath = ""
+			req.PathMapping = config.PathMappingFixed
+			plan, err := Build(context.Background(), req)
+			if err != nil {
+				t.Fatalf("Build() error = %v", err)
+			}
+			if plan.Action != ActionReplaceOlder {
+				t.Fatalf("plan action = %s, want replace_older", plan.Action)
+			}
+			if err := Execute(context.Background(), req, plan); err != nil {
+				t.Fatalf("Execute() error = %v", err)
+			}
+			testutil.AssertFakeFile(t, destinationBackend, "report.md", "# Report\nNew.\n")
+			destinationState := readFakeState(t, destinationBackend, "")
+			if got, want := destinationState.Reconciliation.Mode, mode; got != want {
+				t.Fatalf("state reconciliation mode = %q, want %q", got, want)
+			}
+		})
+	}
+}
+
+func TestExecuteReconciliationModesHonorPublishPolicies(t *testing.T) {
+	tests := []struct {
+		name        string
+		publish     config.PublishPolicy
+		transform   config.Transform
+		transformer TransformerResolver
+		wantPaths   []string
+	}{
+		{
+			name:      "source only",
+			publish:   config.PublishPolicy{Source: true},
+			wantPaths: []string{"report.md"},
+		},
+		{
+			name:      "generated only",
+			publish:   config.PublishPolicy{HTML: true},
+			transform: config.Transform{MarkdownToHTML: &config.MarkdownToHTML{Enabled: true, Mode: config.TransformModeSidecar}},
+			transformer: testResolver{transform.MarkdownToHTML: testTransformer{outputs: []transform.Output{{
+				Path:       "report.html",
+				SourcePath: "report.md",
+				Transform:  transform.MarkdownToHTML,
+				Data:       []byte("<h1>Report</h1>\n"),
+				SHA256:     bundle.FileDigest([]byte("<h1>Report</h1>\n")),
+				Size:       int64(len("<h1>Report</h1>\n")),
+			}}}},
+			wantPaths: []string{"report.html"},
+		},
+		{
+			name:      "source and generated",
+			publish:   config.PublishPolicy{Source: true, HTML: true},
+			transform: config.Transform{MarkdownToHTML: &config.MarkdownToHTML{Enabled: true, Mode: config.TransformModeSidecar}},
+			transformer: testResolver{transform.MarkdownToHTML: testTransformer{outputs: []transform.Output{{
+				Path:       "report.html",
+				SourcePath: "report.md",
+				Transform:  transform.MarkdownToHTML,
+				Data:       []byte("<h1>Report</h1>\n"),
+				SHA256:     bundle.FileDigest([]byte("<h1>Report</h1>\n")),
+				Size:       int64(len("<h1>Report</h1>\n")),
+			}}}},
+			wantPaths: []string{"report.md", "report.html"},
+		},
+	}
+	for _, mode := range []string{config.ReconciliationModeReplace, config.ReconciliationModeMerge} {
+		for _, tt := range tests {
+			t.Run(mode+" "+tt.name, func(t *testing.T) {
+				sourceBackend := fake.New()
+				sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "", testutil.BundleOptions{
+					Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\nNew.\n"}},
+				})
+				destinationBackend := fake.New()
+				older := sourceBundle.Manifest
+				older.Created = older.Created.Add(-time.Hour)
+				testutil.WriteFakeDestinationState(t, destinationBackend, "", older, testutil.DestinationStateOptions{})
+
+				req := testRequest(sourceBackend, destinationBackend, sourceBundle, mode)
+				req.Publish = tt.publish
+				req.Transform = tt.transform
+				req.Transformers = tt.transformer
+				plan, err := Build(context.Background(), req)
+				if err != nil {
+					t.Fatalf("Build() error = %v", err)
+				}
+				if err := Execute(context.Background(), req, plan); err != nil {
+					t.Fatalf("Execute() error = %v", err)
+				}
+				destinationState := readFakeState(t, destinationBackend, "")
+				outputs := outputsByPath(destinationState.Outputs)
+				for _, path := range tt.wantPaths {
+					if _, ok := outputs[path]; !ok {
+						t.Fatalf("state outputs = %#v, missing %s", destinationState.Outputs, path)
+					}
+				}
+			})
+		}
+	}
+}
+
 type failingBackend struct {
 	*fake.Backend
 	failPath string
@@ -62,3 +310,48 @@ func (b *failingBackend) WriteFrom(ctx context.Context, path string, r io.Reader
 	}
 	return b.Backend.WriteFrom(ctx, path, r, opts)
 }
+
+func testRequest(sourceBackend storage.Backend, destinationBackend storage.Backend, sourceBundle bundle.Bundle, reconciliationMode string) Request {
+	return Request{
+		PipelineID:            "reports",
+		DestinationID:         "archive",
+		SourceBundle:          sourceBundle,
+		SourceBackend:         sourceBackend,
+		DestinationBackend:    destinationBackend,
+		DestinationBundlePath: sourceBundle.RootRelativePath,
+		Publish:               config.PublishPolicy{Source: true},
+		Reconciliation:        config.ReconciliationPolicy{Mode: reconciliationMode},
+		Transfer: config.TransferPolicy{
+			OnDestinationSame:  config.TransferActionSkip,
+			OnDestinationOlder: config.TransferActionReplace,
+			OnDestinationNewer: config.TransferActionSkip,
+			OnConflict:         config.TransferActionFail,
+		},
+		DistributorVersion: "test",
+	}
+}
+
+func readFakeState(t *testing.T, backend storage.Backend, bundlePath string) state.DistributorState {
+	t.Helper()
+	statePath, err := storage.StatePath(bundlePath)
+	if err != nil {
+		t.Fatalf("state path: %v", err)
+	}
+	data, err := backend.ReadFile(context.Background(), statePath)
+	if err != nil {
+		t.Fatalf("read state: %v", err)
+	}
+	destinationState, err := state.Parse(data)
+	if err != nil {
+		t.Fatalf("parse state: %v", err)
+	}
+	return destinationState
+}
+
+func outputsByPath(outputs []state.OutputFile) map[string]state.OutputFile {
+	byPath := make(map[string]state.OutputFile, len(outputs))
+	for _, output := range outputs {
+		byPath[output.Path] = output
+	}
+	return byPath
+}

internal/publish/output.go

@@ -109,6 +109,18 @@ func (o Output) StateOutputFile() state.OutputFile {
 	}
 }
 
+func (o Output) StateOutputProjection() state.OutputProjection {
+	return state.OutputProjection{
+		Path:       o.DestinationPath,
+		Kind:       o.Kind,
+		SourcePath: o.SourcePath,
+		Transform:  o.Transform,
+		URL:        o.URL,
+		SHA256:     o.SHA256,
+		Size:       o.Size,
+	}
+}
+
 func (o Output) ManagedPath() string {
 	return o.DestinationPath
 }
@@ -121,6 +133,14 @@ func StateOutputFiles(outputs []Output) []state.OutputFile {
 	return files
 }
 
+func StateOutputProjections(outputs []Output) []state.OutputProjection {
+	projections := make([]state.OutputProjection, 0, len(outputs))
+	for _, output := range outputs {
+		projections = append(projections, output.StateOutputProjection())
+	}
+	return projections
+}
+
 func ManagedOutputPaths(outputs []Output) []string {
 	paths := make([]string, 0, len(outputs))
 	for _, output := range outputs {
@@ -128,11 +148,3 @@ func ManagedOutputPaths(outputs []Output) []string {
 	}
 	return paths
 }
-
-func stateOutputManagedPaths(outputs []state.OutputFile) []string {
-	paths := make([]string, 0, len(outputs))
-	for _, output := range outputs {
-		paths = append(paths, output.Path)
-	}
-	return paths
-}

internal/publish/plan.go

@@ -34,6 +34,8 @@ type Request struct {
 	Publish               config.PublishPolicy
 	Transform             config.Transform
 	Links                 *config.Links
+	State                 config.StatePolicy
+	Reconciliation        config.ReconciliationPolicy
 	Transformers          TransformerResolver
 	Transfer              config.TransferPolicy
 	DistributorVersion    string
@@ -55,8 +57,16 @@ type Plan struct {
 	Reason                string
 	Force                 bool
 	PrimaryURL            string
+	StateMode             string
+	OwnerScope            state.OwnerScope
+	Reconciliation        config.ReconciliationPolicy
 	Outputs               []Output
 	ExistingState         *state.DistributorState
+	ExistingSharedRoot    *state.SharedRootState
+	OtherOwnerOutputs     []state.SharedRootOutputFile
+	RetainedOwnerOutputs  []state.SharedRootOutputFile
+	OwnerOutputsToDelete  []state.SharedRootOutputFile
+	OwnerOutputsToWrite   []Output
 }
 
 type Output struct {
@@ -88,6 +98,8 @@ func Build(ctx context.Context, req Request) (Plan, error) {
 	}
 	comparison := compareDestination(req, status)
 	action, reason := actionForComparison(comparison, req.Transfer, req.Force)
+	reconciliation := normalizeReconciliation(req.Reconciliation)
+	stateMode := normalizeState(req.State).Mode
 	plan := Plan{
 		PipelineID:            req.PipelineID,
 		DestinationID:         req.DestinationID,
@@ -99,8 +111,24 @@ func Build(ctx context.Context, req Request) (Plan, error) {
 		Reason:                reason,
 		Force:                 action == ActionForceReplace,
 		PrimaryURL:            primaryURL,
+		StateMode:             stateMode,
+		OwnerScope:            state.CurrentOwnerScope(req.PipelineID, req.DestinationID),
+		Reconciliation:        reconciliation,
 		Outputs:               outputs,
 		ExistingState:         status.State,
+		ExistingSharedRoot:    status.SharedRoot,
+	}
+	if stateMode == config.StateModeSharedRoot {
+		sharedDetails, err := planSharedRootOwner(ctx, req, status, action, reconciliation, outputs)
+		plan.OtherOwnerOutputs = sharedDetails.OtherOwnerOutputs
+		plan.RetainedOwnerOutputs = sharedDetails.RetainedOwnerOutputs
+		plan.OwnerOutputsToDelete = sharedDetails.OwnerOutputsToDelete
+		plan.OwnerOutputsToWrite = sharedDetails.OwnerOutputsToWrite
+		if err != nil {
+			plan.Action = sharedDetails.Action
+			plan.Reason = sharedDetails.Reason
+			return plan, err
+		}
 	}
 	if action == ActionFailConflict || action == ActionFailUnmanaged {
 		return plan, fmt.Errorf("%s: %s", action, reason)
@@ -124,10 +152,52 @@ func validateRequest(req Request) error {
 	if err := config.ValidatePublishTransformPolicy(req.Publish, req.Transform); err != nil {
 		return fmt.Errorf("publish/transform policy: %w", err)
 	}
+	switch normalizeReconciliation(req.Reconciliation).Mode {
+	case config.ReconciliationModeReplace, config.ReconciliationModeMerge:
+	default:
+		return fmt.Errorf("reconciliation.mode must be %s or %s", config.ReconciliationModeReplace, config.ReconciliationModeMerge)
+	}
+	switch normalizeState(req.State).Mode {
+	case config.StateModeSingleOwner, config.StateModeSharedRoot:
+	default:
+		return fmt.Errorf("state.mode must be %s or %s", config.StateModeSingleOwner, config.StateModeSharedRoot)
+	}
 	return nil
 }
 
+func normalizeReconciliation(policy config.ReconciliationPolicy) config.ReconciliationPolicy {
+	if policy.Mode == "" {
+		policy.Mode = config.ReconciliationModeReplace
+	}
+	return policy
+}
+
+func normalizeState(policy config.StatePolicy) config.StatePolicy {
+	if policy.Mode == "" {
+		policy.Mode = config.StateModeSingleOwner
+	}
+	return policy
+}
+
 func compareDestination(req Request, status state.DestinationStatus) state.Comparison {
+	if normalizeState(req.State).Mode == config.StateModeSharedRoot {
+		scope := state.CurrentOwnerScope(req.PipelineID, req.DestinationID)
+		comparison := state.CompareSharedRootOwner(req.SourceBundle.Manifest, scope, status)
+		if req.PathMapping != config.PathMappingFixed || comparison.Outcome != state.OutcomeDifferentSourceConflict {
+			return comparison
+		}
+		destinationManifest, ok := sharedRootComparisonManifest(status, scope)
+		if !ok {
+			return comparison
+		}
+		if destinationManifest.Created.Before(req.SourceBundle.Manifest.Created) {
+			return state.Comparison{Outcome: state.OutcomeDestinationOlder, Reason: "fixed destination source is older than selected source"}
+		}
+		if destinationManifest.Created.After(req.SourceBundle.Manifest.Created) {
+			return state.Comparison{Outcome: state.OutcomeDestinationNewer, Reason: "fixed destination source is newer than selected source"}
+		}
+		return comparison
+	}
 	comparison := state.Compare(req.SourceBundle.Manifest, req.PipelineID, req.DestinationID, status)
 	if req.PathMapping != config.PathMappingFixed || comparison.Outcome != state.OutcomeDifferentSourceConflict || status.State == nil {
 		return comparison
@@ -142,6 +212,173 @@ func compareDestination(req Request, status state.DestinationStatus) state.Compa
 	return comparison
 }
 
+func sharedRootComparisonManifest(status state.DestinationStatus, scope state.OwnerScope) (bundle.Manifest, bool) {
+	if status.SharedRoot != nil {
+		return status.SharedRoot.SourceManifest(scope)
+	}
+	if status.State != nil && status.State.PipelineID == scope.PipelineID && status.State.DestinationID == scope.DestinationID {
+		return status.State.Source.Manifest, true
+	}
+	return bundle.Manifest{}, false
+}
+
+type sharedRootPlanDetails struct {
+	Action               Action
+	Reason               string
+	OtherOwnerOutputs    []state.SharedRootOutputFile
+	RetainedOwnerOutputs []state.SharedRootOutputFile
+	OwnerOutputsToDelete []state.SharedRootOutputFile
+	OwnerOutputsToWrite  []Output
+}
+
+func planSharedRootOwner(ctx context.Context, req Request, status state.DestinationStatus, action Action, reconciliation config.ReconciliationPolicy, outputs []Output) (sharedRootPlanDetails, error) {
+	scope := state.CurrentOwnerScope(req.PipelineID, req.DestinationID)
+	details := sharedRootPlanDetails{Action: action}
+	if !isWriteAction(action) {
+		details.OtherOwnerOutputs = otherOwnerOutputs(status, scope)
+		return details, nil
+	}
+
+	plannedPaths := outputPaths(outputs)
+	if action == ActionForceReplace {
+		details.OwnerOutputsToWrite = append([]Output(nil), outputs...)
+		return details, nil
+	}
+	if conflict, ok := sharedRootPathOwnershipConflict(status, scope, plannedPaths); ok {
+		reason := fmt.Sprintf("destination output path %s is owned by %s/%s", conflict.Path, conflict.Owner.PipelineID, conflict.Owner.DestinationID)
+		details.Action = ActionFailConflict
+		details.Reason = reason
+		return details, fmt.Errorf("%s: %s", ActionFailConflict, reason)
+	}
+	if err := rejectSharedRootUnmanagedCollisions(ctx, req.DestinationBackend, req.DestinationBundlePath, status, scope, plannedPaths); err != nil {
+		details.Action = ActionFailUnmanaged
+		details.Reason = err.Error()
+		return details, fmt.Errorf("%s: %s", ActionFailUnmanaged, err)
+	}
+
+	details.OtherOwnerOutputs = otherOwnerOutputs(status, scope)
+	ownerOutputs := currentOwnerOutputs(status, scope)
+	planned := make(map[string]struct{}, len(plannedPaths))
+	for _, path := range plannedPaths {
+		planned[path] = struct{}{}
+	}
+	for _, output := range ownerOutputs {
+		if _, exists := planned[output.Path]; exists {
+			continue
+		}
+		if action == ActionReplaceOlder && reconciliation.Mode == config.ReconciliationModeReplace {
+			details.OwnerOutputsToDelete = append(details.OwnerOutputsToDelete, output)
+			continue
+		}
+		if action == ActionReplaceOlder && reconciliation.Mode == config.ReconciliationModeMerge {
+			details.RetainedOwnerOutputs = append(details.RetainedOwnerOutputs, output)
+		}
+	}
+	details.OwnerOutputsToWrite = append([]Output(nil), outputs...)
+	return details, nil
+}
+
+func isWriteAction(action Action) bool {
+	switch action {
+	case ActionPublishNew, ActionReplaceOlder, ActionForceReplace:
+		return true
+	default:
+		return false
+	}
+}
+
+func outputPaths(outputs []Output) []string {
+	paths := make([]string, 0, len(outputs))
+	for _, output := range outputs {
+		paths = append(paths, output.DestinationPath)
+	}
+	return paths
+}
+
+func sharedRootPathOwnershipConflict(status state.DestinationStatus, scope state.OwnerScope, paths []string) (state.PathOwnershipConflict, bool) {
+	if status.SharedRoot != nil {
+		return status.SharedRoot.PathOwnershipConflict(scope, paths)
+	}
+	return state.PathOwnershipConflict{}, false
+}
+
+func rejectSharedRootUnmanagedCollisions(ctx context.Context, backend storage.Backend, bundlePath string, status state.DestinationStatus, scope state.OwnerScope, paths []string) error {
+	for _, path := range paths {
+		if pathManagedBySharedRootStatus(status, scope, path) {
+			continue
+		}
+		destinationPath, err := storage.Join(bundlePath, path)
+		if err != nil {
+			return err
+		}
+		if _, err := backend.Stat(ctx, destinationPath); err == nil {
+			return fmt.Errorf("destination output path %s exists but is not managed by destination state", storage.DisplayPath(path))
+		} else if !storage.IsNotFound(err) {
+			return err
+		}
+	}
+	return nil
+}
+
+func pathManagedBySharedRootStatus(status state.DestinationStatus, scope state.OwnerScope, path string) bool {
+	if status.SharedRoot != nil {
+		_, exists := status.SharedRoot.OutputOwner(path)
+		return exists
+	}
+	if status.State != nil && status.State.PipelineID == scope.PipelineID && status.State.DestinationID == scope.DestinationID {
+		_, exists := state.FindOutputByPath(status.State.Outputs, path)
+		return exists
+	}
+	return false
+}
+
+func otherOwnerOutputs(status state.DestinationStatus, scope state.OwnerScope) []state.SharedRootOutputFile {
+	if status.SharedRoot == nil {
+		return nil
+	}
+	outputs := make([]state.SharedRootOutputFile, 0, len(status.SharedRoot.Outputs))
+	for _, output := range status.SharedRoot.Outputs {
+		if output.Owner != scope {
+			outputs = append(outputs, output)
+		}
+	}
+	return outputs
+}
+
+func currentOwnerOutputs(status state.DestinationStatus, scope state.OwnerScope) []state.SharedRootOutputFile {
+	if status.SharedRoot != nil {
+		outputs := make([]state.SharedRootOutputFile, 0, len(status.SharedRoot.Outputs))
+		for _, output := range status.SharedRoot.Outputs {
+			if output.Owner == scope {
+				outputs = append(outputs, output)
+			}
+		}
+		return outputs
+	}
+	if status.State != nil && status.State.PipelineID == scope.PipelineID && status.State.DestinationID == scope.DestinationID {
+		outputs := make([]state.SharedRootOutputFile, 0, len(status.State.Outputs))
+		for _, output := range status.State.Outputs {
+			outputs = append(outputs, state.SharedRootOutputFile{
+				Path:          output.Path,
+				Kind:          output.Kind,
+				SourcePath:    output.SourcePath,
+				Transform:     output.Transform,
+				URL:           output.URL,
+				SHA256:        output.SHA256,
+				Size:          output.Size,
+				Owner:         scope,
+				SourceID:      status.State.Source.Manifest.ID,
+				SourceDigest:  status.State.Source.Manifest.Digest,
+				SourceCreated: status.State.Source.Manifest.Created,
+				CreatedAt:     output.CreatedAt,
+				UpdatedAt:     output.UpdatedAt,
+			})
+		}
+		return outputs
+	}
+	return nil
+}
+
 func actionForComparison(comparison state.Comparison, transfer config.TransferPolicy, force bool) (Action, string) {
 	switch comparison.Outcome {
 	case state.OutcomeDestinationAbsent:

internal/publish/reconcile.go

@@ -14,11 +14,11 @@ func inspectDestination(ctx context.Context, backend storage.Backend, bundlePath
 	}
 	data, err := backend.ReadFile(ctx, statePath)
 	if err == nil {
-		destinationState, parseErr := state.Parse(data)
+		document, parseErr := state.ParseDocument(data)
 		if parseErr != nil {
 			return state.DestinationStatus{StateErr: parseErr}, nil
 		}
-		return state.DestinationStatus{State: &destinationState, HasContents: true}, nil
+		return state.DestinationStatus{State: document.SingleOwner, SharedRoot: document.SharedRoot, HasContents: true}, nil
 	}
 	if !storage.IsNotFound(err) {
 		return state.DestinationStatus{}, err

internal/publish/shared_root_test.go

@@ -0,0 +1,399 @@
+package publish
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/state"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage/fake"
+	"gitea.maximumdirect.net/eric/distributor/internal/testutil"
+)
+
+func TestBuildSharedRootTreatsAbsentOwnerAsPublishable(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\n"}},
+	})
+	destinationBackend := fake.New()
+	writeFakeSharedRootState(t, destinationBackend, "bundle", sharedRootStateWithOwners(t, sourceBundle.Manifest, false))
+
+	req := sharedRootRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeReplace)
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	if plan.Action != ActionPublishNew {
+		t.Fatalf("plan action = %s, want publish_new", plan.Action)
+	}
+	if plan.OwnerScope != state.CurrentOwnerScope("reports", "archive") {
+		t.Fatalf("owner scope = %#v, want reports/archive", plan.OwnerScope)
+	}
+	if got, want := len(plan.OtherOwnerOutputs), 1; got != want {
+		t.Fatalf("other owner output count = %d, want %d", got, want)
+	}
+	if got, want := len(plan.OwnerOutputsToWrite), 1; got != want {
+		t.Fatalf("owner output write count = %d, want %d", got, want)
+	}
+	if len(plan.OwnerOutputsToDelete) != 0 || len(plan.RetainedOwnerOutputs) != 0 {
+		t.Fatalf("delete=%#v retained=%#v, want none", plan.OwnerOutputsToDelete, plan.RetainedOwnerOutputs)
+	}
+}
+
+func TestBuildSharedRootReplaceDeletesOnlyCurrentOwnerOmittedOutputs(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\nNew.\n"}},
+	})
+	destinationBackend := fake.New()
+	writeFakeSharedRootState(t, destinationBackend, "bundle", sharedRootStateWithOwners(t, sourceBundle.Manifest, true))
+
+	req := sharedRootRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeReplace)
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	if plan.Action != ActionReplaceOlder {
+		t.Fatalf("plan action = %s, want replace_older", plan.Action)
+	}
+	if got, want := sharedRootOutputPathList(plan.OwnerOutputsToDelete), "old.md"; got != want {
+		t.Fatalf("owner outputs to delete = %q, want %q", got, want)
+	}
+	if got, want := sharedRootOutputPathList(plan.OtherOwnerOutputs), "other/report.md"; got != want {
+		t.Fatalf("other owner outputs = %q, want %q", got, want)
+	}
+	if len(plan.RetainedOwnerOutputs) != 0 {
+		t.Fatalf("retained owner outputs = %#v, want none", plan.RetainedOwnerOutputs)
+	}
+}
+
+func TestBuildSharedRootMergeRetainsCurrentOwnerOmittedOutputs(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\nNew.\n"}},
+	})
+	destinationBackend := fake.New()
+	writeFakeSharedRootState(t, destinationBackend, "bundle", sharedRootStateWithOwners(t, sourceBundle.Manifest, true))
+
+	req := sharedRootRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeMerge)
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	if got, want := sharedRootOutputPathList(plan.RetainedOwnerOutputs), "old.md"; got != want {
+		t.Fatalf("retained owner outputs = %q, want %q", got, want)
+	}
+	if len(plan.OwnerOutputsToDelete) != 0 {
+		t.Fatalf("owner outputs to delete = %#v, want none", plan.OwnerOutputsToDelete)
+	}
+}
+
+func TestBuildSharedRootRejectsOtherOwnerPathConflict(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\n"}},
+	})
+	destinationBackend := fake.New()
+	sharedRoot := sharedRootStateWithOwners(t, sourceBundle.Manifest, false)
+	sharedRoot.Outputs[0].Path = "report.md"
+	writeFakeSharedRootState(t, destinationBackend, "bundle", sharedRoot)
+
+	req := sharedRootRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeReplace)
+	plan, err := Build(context.Background(), req)
+	if err == nil || !strings.Contains(err.Error(), "fail_conflict") {
+		t.Fatalf("Build() error = %v, want fail_conflict", err)
+	}
+	if plan.Action != ActionFailConflict {
+		t.Fatalf("plan action = %s, want fail_conflict", plan.Action)
+	}
+}
+
+func TestBuildSharedRootRejectsUnmanagedPathCollision(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\n"}},
+	})
+	destinationBackend := fake.New()
+	writeFakeSharedRootState(t, destinationBackend, "bundle", sharedRootStateWithOwners(t, sourceBundle.Manifest, false))
+	testutil.WriteFakeFile(t, destinationBackend, "bundle/report.md", "unmanaged")
+
+	req := sharedRootRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeReplace)
+	plan, err := Build(context.Background(), req)
+	if err == nil || !strings.Contains(err.Error(), "fail_unmanaged") {
+		t.Fatalf("Build() error = %v, want fail_unmanaged", err)
+	}
+	if plan.Action != ActionFailUnmanaged {
+		t.Fatalf("plan action = %s, want fail_unmanaged", plan.Action)
+	}
+}
+
+func TestExecuteSharedRootPublishesOwnerAndPreservesOtherOwners(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\n"}},
+	})
+	destinationBackend := fake.New()
+	writeFakeSharedRootState(t, destinationBackend, "bundle", sharedRootStateWithOwners(t, sourceBundle.Manifest, false))
+	req := sharedRootRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeReplace)
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	if err := Execute(context.Background(), req, plan); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	testutil.AssertFakeFile(t, destinationBackend, "bundle/report.md", "# Report\n")
+	testutil.AssertFakeFile(t, destinationBackend, "bundle/other/report.md", "old")
+	destinationState := readFakeSharedRootState(t, destinationBackend, "bundle")
+	if got, want := len(destinationState.Owners), 2; got != want {
+		t.Fatalf("owner count = %d, want %d", got, want)
+	}
+	if got, want := destinationState.State.Mode, state.StateModeSharedRoot; got != want {
+		t.Fatalf("state mode = %q, want %q", got, want)
+	}
+	if _, ok := destinationState.Owner(state.CurrentOwnerScope("other", "archive")); !ok {
+		t.Fatal("other owner missing from shared-root state")
+	}
+	if _, ok := destinationState.Owner(state.CurrentOwnerScope("reports", "archive")); !ok {
+		t.Fatal("current owner missing from shared-root state")
+	}
+	if got, want := strings.Join(destinationState.AllManagedOutputPaths(), ","), "other/report.md,report.md"; got != want {
+		t.Fatalf("managed paths = %q, want %q", got, want)
+	}
+}
+
+func TestExecuteSharedRootReplaceDeletesOnlyCurrentOwnerOmittedOutputs(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\nNew.\n"}},
+	})
+	destinationBackend := fake.New()
+	existing := sharedRootStateWithOwners(t, sourceBundle.Manifest, true)
+	writeFakeSharedRootState(t, destinationBackend, "bundle", existing)
+
+	req := sharedRootRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeReplace)
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	if err := Execute(context.Background(), req, plan); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	testutil.AssertFakeFile(t, destinationBackend, "bundle/report.md", "# Report\nNew.\n")
+	testutil.AssertFakeMissing(t, destinationBackend, "bundle/old.md")
+	testutil.AssertFakeFile(t, destinationBackend, "bundle/other/report.md", "old")
+	destinationState := readFakeSharedRootState(t, destinationBackend, "bundle")
+	if got, want := strings.Join(destinationState.AllManagedOutputPaths(), ","), "other/report.md,report.md"; got != want {
+		t.Fatalf("managed paths = %q, want %q", got, want)
+	}
+	if !destinationState.CreatedAt.Equal(existing.CreatedAt) {
+		t.Fatalf("created_at = %s, want %s", destinationState.CreatedAt, existing.CreatedAt)
+	}
+	output, ok := findSharedRootOutputForTest(destinationState.Outputs, "report.md")
+	if !ok {
+		t.Fatal("report.md missing from shared-root outputs")
+	}
+	if !output.CreatedAt.Equal(existing.Outputs[1].CreatedAt) || !output.UpdatedAt.After(existing.Outputs[1].UpdatedAt) {
+		t.Fatalf("report.md timestamps = created:%s updated:%s, want preserved created and newer updated", output.CreatedAt, output.UpdatedAt)
+	}
+}
+
+func TestExecuteSharedRootMergeRetainsCurrentOwnerOmittedOutputs(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\nNew.\n"}},
+	})
+	destinationBackend := fake.New()
+	writeFakeSharedRootState(t, destinationBackend, "bundle", sharedRootStateWithOwners(t, sourceBundle.Manifest, true))
+
+	req := sharedRootRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeMerge)
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	if err := Execute(context.Background(), req, plan); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	testutil.AssertFakeFile(t, destinationBackend, "bundle/report.md", "# Report\nNew.\n")
+	testutil.AssertFakeFile(t, destinationBackend, "bundle/old.md", "old")
+	testutil.AssertFakeFile(t, destinationBackend, "bundle/other/report.md", "old")
+	destinationState := readFakeSharedRootState(t, destinationBackend, "bundle")
+	if got, want := strings.Join(destinationState.AllManagedOutputPaths(), ","), "other/report.md,report.md,old.md"; got != want {
+		t.Fatalf("managed paths = %q, want %q", got, want)
+	}
+}
+
+func TestExecuteSharedRootForceReplaceDeletesOnlyBundlePath(t *testing.T) {
+	sourceBackend := fake.New()
+	sourceBundle := testutil.WriteFakeSourceBundle(t, sourceBackend, "bundle", testutil.BundleOptions{
+		Files: []testutil.SourceFile{{Path: "report.md", Data: "# Report\n"}},
+	})
+	destinationBackend := fake.New()
+	testutil.WriteFakeFile(t, destinationBackend, "bundle/unmanaged.txt", "unmanaged")
+	testutil.WriteFakeFile(t, destinationBackend, "bundle/nested/old.txt", "old")
+	testutil.WriteFakeFile(t, destinationBackend, "bundle-sibling/keep.txt", "keep")
+
+	req := sharedRootRequest(sourceBackend, destinationBackend, sourceBundle, config.ReconciliationModeReplace)
+	req.Force = true
+	plan, err := Build(context.Background(), req)
+	if err != nil {
+		t.Fatalf("Build() error = %v", err)
+	}
+	if plan.Action != ActionForceReplace {
+		t.Fatalf("plan action = %s, want force_replace", plan.Action)
+	}
+	if err := Execute(context.Background(), req, plan); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	testutil.AssertFakeFile(t, destinationBackend, "bundle/report.md", "# Report\n")
+	testutil.AssertFakeMissing(t, destinationBackend, "bundle/unmanaged.txt")
+	testutil.AssertFakeMissing(t, destinationBackend, "bundle/nested/old.txt")
+	testutil.AssertFakeFile(t, destinationBackend, "bundle-sibling/keep.txt", "keep")
+	destinationState := readFakeSharedRootState(t, destinationBackend, "bundle")
+	if got, want := len(destinationState.Owners), 1; got != want {
+		t.Fatalf("owner count = %d, want %d", got, want)
+	}
+}
+
+func sharedRootRequest(sourceBackend, destinationBackend *fake.Backend, sourceBundle bundle.Bundle, reconciliationMode string) Request {
+	return Request{
+		PipelineID:            "reports",
+		DestinationID:         "archive",
+		SourceBundle:          sourceBundle,
+		SourceBackend:         sourceBackend,
+		DestinationBackend:    destinationBackend,
+		DestinationBundlePath: sourceBundle.RootRelativePath,
+		Publish:               config.PublishPolicy{Source: true},
+		State:                 config.StatePolicy{Mode: config.StateModeSharedRoot},
+		Reconciliation:        config.ReconciliationPolicy{Mode: reconciliationMode},
+		Transfer:              defaultTransfer(),
+		DistributorVersion:    "test",
+	}
+}
+
+func writeFakeSharedRootState(t *testing.T, backend *fake.Backend, relative string, sharedRoot state.SharedRootState) {
+	t.Helper()
+	data, err := json.MarshalIndent(sharedRoot, "", "  ")
+	if err != nil {
+		t.Fatalf("marshal shared-root state: %v", err)
+	}
+	statePath, err := storage.StatePath(relative)
+	if err != nil {
+		t.Fatalf("state path: %v", err)
+	}
+	testutil.WriteFakeFile(t, backend, statePath, string(append(data, '\n')))
+	for _, output := range sharedRoot.Outputs {
+		path, err := storage.Join(relative, output.Path)
+		if err != nil {
+			t.Fatalf("join output path: %v", err)
+		}
+		testutil.WriteFakeFile(t, backend, path, "old")
+	}
+}
+
+func readFakeSharedRootState(t *testing.T, backend *fake.Backend, relative string) state.SharedRootState {
+	t.Helper()
+	statePath, err := storage.StatePath(relative)
+	if err != nil {
+		t.Fatalf("state path: %v", err)
+	}
+	data, err := backend.ReadFile(context.Background(), statePath)
+	if err != nil {
+		t.Fatalf("read shared-root state: %v", err)
+	}
+	destinationState, err := state.ParseSharedRoot(data)
+	if err != nil {
+		t.Fatalf("parse shared-root state: %v", err)
+	}
+	return destinationState
+}
+
+func findSharedRootOutputForTest(outputs []state.SharedRootOutputFile, path string) (state.SharedRootOutputFile, bool) {
+	for _, output := range outputs {
+		if output.Path == path {
+			return output, true
+		}
+	}
+	return state.SharedRootOutputFile{}, false
+}
+
+func sharedRootStateWithOwners(t *testing.T, current bundle.Manifest, includeCurrent bool) state.SharedRootState {
+	t.Helper()
+	createdAt := time.Date(2026, 5, 30, 11, 12, 0, 0, time.UTC)
+	otherManifest := testutil.ValidManifest(testutil.BundleOptions{
+		ID:    "other.source",
+		Files: []testutil.SourceFile{{Path: "other/report.md", Data: "# Other\n"}},
+	})
+	sharedRoot := state.SharedRootState{
+		SchemaVersion:      state.SharedRootSchemaVersion,
+		DistributorVersion: "test",
+		CreatedAt:          createdAt,
+		UpdatedAt:          createdAt,
+		State:              state.StatePolicy{Mode: state.StateModeSharedRoot},
+		Owners: []state.OwnerRecord{{
+			Scope:          state.CurrentOwnerScope("other", "archive"),
+			Reconciliation: state.ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
+			Source:         state.SourceState{Manifest: otherManifest},
+		}},
+		Outputs: []state.SharedRootOutputFile{{
+			Path:          "other/report.md",
+			Kind:          state.OutputKindSource,
+			SourcePath:    "other/report.md",
+			SHA256:        otherManifest.Files[0].SHA256,
+			Size:          otherManifest.Files[0].Size,
+			Owner:         state.CurrentOwnerScope("other", "archive"),
+			SourceID:      otherManifest.ID,
+			SourceDigest:  otherManifest.Digest,
+			SourceCreated: otherManifest.Created,
+			CreatedAt:     createdAt,
+			UpdatedAt:     createdAt,
+		}},
+	}
+	if !includeCurrent {
+		return sharedRoot
+	}
+	older := current
+	older.Created = older.Created.Add(-time.Hour)
+	older.Files = append([]bundle.ManifestFile(nil), current.Files...)
+	older.Files = append(older.Files, bundle.ManifestFile{
+		Path:   "old.md",
+		SHA256: bundle.FileDigest([]byte("old\n")),
+		Size:   int64(len("old\n")),
+	})
+	older.Digest = bundle.BundleDigest(older.Files)
+	scope := state.CurrentOwnerScope("reports", "archive")
+	sharedRoot.Owners = append(sharedRoot.Owners, state.OwnerRecord{
+		Scope:          scope,
+		Reconciliation: state.ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
+		Source:         state.SourceState{Manifest: older},
+	})
+	for _, file := range older.Files {
+		sharedRoot.Outputs = append(sharedRoot.Outputs, state.SharedRootOutputFile{
+			Path:          file.Path,
+			Kind:          state.OutputKindSource,
+			SourcePath:    file.Path,
+			SHA256:        file.SHA256,
+			Size:          file.Size,
+			Owner:         scope,
+			SourceID:      older.ID,
+			SourceDigest:  older.Digest,
+			SourceCreated: older.Created,
+			CreatedAt:     createdAt,
+			UpdatedAt:     createdAt,
+		})
+	}
+	return sharedRoot
+}
+
+func sharedRootOutputPathList(outputs []state.SharedRootOutputFile) string {
+	paths := make([]string, 0, len(outputs))
+	for _, output := range outputs {
+		paths = append(paths, output.Path)
+	}
+	return strings.Join(paths, ",")
+}

internal/state/compare.go

@@ -22,6 +22,7 @@ const (
 
 type DestinationStatus struct {
 	State       *DistributorState
+	SharedRoot  *SharedRootState
 	StateErr    error
 	HasContents bool
 }
@@ -31,6 +32,58 @@ type Comparison struct {
 	Reason  string
 }
 
+func CompareSharedRootOwner(source bundle.Manifest, scope OwnerScope, status DestinationStatus) Comparison {
+	if status.StateErr != nil {
+		return Comparison{Outcome: OutcomeInvalidState, Reason: status.StateErr.Error()}
+	}
+	if status.SharedRoot != nil {
+		if err := ValidateSharedRoot(*status.SharedRoot); err != nil {
+			return Comparison{Outcome: OutcomeInvalidState, Reason: err.Error()}
+		}
+		owner, ok := status.SharedRoot.Owner(scope)
+		if !ok {
+			return Comparison{Outcome: OutcomeDestinationAbsent, Reason: fmt.Sprintf("destination owner %s/%s is absent", scope.PipelineID, scope.DestinationID)}
+		}
+		return compareManifests(source, owner.Source.Manifest)
+	}
+	if status.State != nil {
+		destinationState := *status.State
+		if err := Validate(destinationState); err != nil {
+			return Comparison{Outcome: OutcomeInvalidState, Reason: err.Error()}
+		}
+		if destinationState.PipelineID != scope.PipelineID {
+			return Comparison{Outcome: OutcomeIdentityMismatch, Reason: fmt.Sprintf("pipeline id %q does not match %q", destinationState.PipelineID, scope.PipelineID)}
+		}
+		if destinationState.DestinationID != scope.DestinationID {
+			return Comparison{Outcome: OutcomeIdentityMismatch, Reason: fmt.Sprintf("destination id %q does not match %q", destinationState.DestinationID, scope.DestinationID)}
+		}
+		return compareManifests(source, destinationState.Source.Manifest)
+	}
+	if status.HasContents {
+		return Comparison{Outcome: OutcomeDestinationUnmanaged, Reason: "destination has content but no distributor state"}
+	}
+	return Comparison{Outcome: OutcomeDestinationAbsent, Reason: "destination state is absent"}
+}
+
+func compareManifests(source, destination bundle.Manifest) Comparison {
+	if manifestsEqual(source, destination) {
+		return Comparison{Outcome: OutcomeSameSource, Reason: "destination source manifest matches source"}
+	}
+	if destination.ID != source.ID {
+		return Comparison{Outcome: OutcomeDifferentSourceConflict, Reason: "destination source id differs from source"}
+	}
+	if destination.Created.Before(source.Created) {
+		return Comparison{Outcome: OutcomeDestinationOlder, Reason: "destination source is older than source"}
+	}
+	if destination.Created.After(source.Created) {
+		return Comparison{Outcome: OutcomeDestinationNewer, Reason: "destination source is newer than source"}
+	}
+	if destination.Digest != source.Digest {
+		return Comparison{Outcome: OutcomeSameCreatedConflict, Reason: "destination source has same id and created time but different digest"}
+	}
+	return Comparison{Outcome: OutcomeInvalidState, Reason: "destination source differs from source without a supported comparison outcome"}
+}
+
 func Compare(source bundle.Manifest, pipelineID, destinationID string, status DestinationStatus) Comparison {
 	if status.StateErr != nil {
 		return Comparison{Outcome: OutcomeInvalidState, Reason: status.StateErr.Error()}
@@ -53,23 +106,7 @@ func Compare(source bundle.Manifest, pipelineID, destinationID string, status De
 		return Comparison{Outcome: OutcomeIdentityMismatch, Reason: fmt.Sprintf("destination id %q does not match %q", destinationState.DestinationID, destinationID)}
 	}
 
-	destinationManifest := destinationState.Source.Manifest
+	return compareManifests(source, destinationState.Source.Manifest)
-	if manifestsEqual(source, destinationManifest) {
-		return Comparison{Outcome: OutcomeSameSource, Reason: "destination source manifest matches source"}
-	}
-	if destinationManifest.ID != source.ID {
-		return Comparison{Outcome: OutcomeDifferentSourceConflict, Reason: "destination source id differs from source"}
-	}
-	if destinationManifest.Created.Before(source.Created) {
-		return Comparison{Outcome: OutcomeDestinationOlder, Reason: "destination source is older than source"}
-	}
-	if destinationManifest.Created.After(source.Created) {
-		return Comparison{Outcome: OutcomeDestinationNewer, Reason: "destination source is newer than source"}
-	}
-	if destinationManifest.Digest != source.Digest {
-		return Comparison{Outcome: OutcomeSameCreatedConflict, Reason: "destination source has same id and created time but different digest"}
-	}
-	return Comparison{Outcome: OutcomeInvalidState, Reason: "destination source differs from source without a supported comparison outcome"}
 }
 
 func manifestsEqual(a, b bundle.Manifest) bool {

internal/state/compare_test.go

@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
 )
 
 func TestCompareOutcomes(t *testing.T) {
@@ -100,18 +101,25 @@ func withState(t *testing.T, source bundle.Manifest, mutate func(*DistributorSta
 	t.Helper()
 	stateManifest := source
 	stateManifest.Files = append([]bundle.ManifestFile(nil), source.Files...)
+	publishedAt := time.Date(2026, 5, 30, 11, 12, 0, 0, time.UTC)
 	state := DistributorState{
-		SchemaVersion: SchemaVersion,
+		SchemaVersion:  SchemaVersion,
-		PipelineID:    "reports",
+		PipelineID:     "reports",
-		DestinationID: "archive",
+		DestinationID:  "archive",
-		PublishedAt:   time.Date(2026, 5, 30, 11, 12, 0, 0, time.UTC),
+		PublishedAt:    publishedAt,
-		Source:        SourceState{Manifest: stateManifest},
+		CreatedAt:      publishedAt,
+		UpdatedAt:      publishedAt,
+		State:          StatePolicy{Mode: StateModeSingleOwner},
+		Reconciliation: ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
+		Source:         SourceState{Manifest: stateManifest},
 		Outputs: []OutputFile{{
 			Path:       "report.md",
 			Kind:       OutputKindSource,
 			SourcePath: "report.md",
 			SHA256:     source.Files[0].SHA256,
 			Size:       source.Files[0].Size,
+			CreatedAt:  publishedAt,
+			UpdatedAt:  publishedAt,
 		}},
 	}
 	if mutate != nil {

internal/state/distributor.go

@@ -8,9 +8,16 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
 )
 
-const SchemaVersion = 1
+const (
+	SchemaVersion           = 2
+	SharedRootSchemaVersion = 3
+	legacySchemaVersion     = 1
+	StateModeSingleOwner    = config.StateModeSingleOwner
+	StateModeSharedRoot     = config.StateModeSharedRoot
+)
 
 type DistributorState struct {
 	SchemaVersion      int
@@ -18,11 +25,23 @@ type DistributorState struct {
 	PipelineID         string
 	DestinationID      string
 	PublishedAt        time.Time
+	CreatedAt          time.Time
+	UpdatedAt          time.Time
+	State              StatePolicy
+	Reconciliation     ReconciliationPolicy
 	Source             SourceState
 	Links              *LinkState
 	Outputs            []OutputFile
 }
 
+type StatePolicy struct {
+	Mode string
+}
+
+type ReconciliationPolicy struct {
+	Mode string
+}
+
 type SourceState struct {
 	Manifest bundle.Manifest
 }
@@ -39,17 +58,31 @@ type OutputFile struct {
 	URL        string
 	SHA256     string
 	Size       int64
+	CreatedAt  time.Time
+	UpdatedAt  time.Time
 }
 
 type rawDistributorState struct {
-	SchemaVersion      *int            `json:"schema_version"`
+	SchemaVersion      *int                     `json:"schema_version"`
-	DistributorVersion string          `json:"distributor_version"`
+	DistributorVersion string                   `json:"distributor_version"`
-	PipelineID         *string         `json:"pipeline_id"`
+	PipelineID         *string                  `json:"pipeline_id"`
-	DestinationID      *string         `json:"destination_id"`
+	DestinationID      *string                  `json:"destination_id"`
-	PublishedAt        *string         `json:"published_at"`
+	PublishedAt        *string                  `json:"published_at"`
-	Source             *rawSourceState `json:"source"`
+	CreatedAt          *string                  `json:"created_at"`
-	Links              *rawLinkState   `json:"links"`
+	UpdatedAt          *string                  `json:"updated_at"`
-	Outputs            []rawOutputFile `json:"outputs"`
+	State              *rawStatePolicy          `json:"state"`
+	Reconciliation     *rawReconciliationPolicy `json:"reconciliation"`
+	Source             *rawSourceState          `json:"source"`
+	Links              *rawLinkState            `json:"links"`
+	Outputs            []rawOutputFile          `json:"outputs"`
+}
+
+type rawStatePolicy struct {
+	Mode string `json:"mode"`
+}
+
+type rawReconciliationPolicy struct {
+	Mode string `json:"mode"`
 }
 
 type rawSourceState struct {
@@ -68,6 +101,8 @@ type rawOutputFile struct {
 	URL        string  `json:"url"`
 	SHA256     *string `json:"sha256"`
 	Size       *int64  `json:"size"`
+	CreatedAt  *string `json:"created_at"`
+	UpdatedAt  *string `json:"updated_at"`
 }
 
 func Parse(data []byte) (DistributorState, error) {
@@ -96,9 +131,10 @@ func parseRaw(raw rawDistributorState) (DistributorState, error) {
 		return DistributorState{}, fmt.Errorf("state schema_version is required")
 	}
 	state.SchemaVersion = *raw.SchemaVersion
-	if state.SchemaVersion != SchemaVersion {
+	if state.SchemaVersion != SchemaVersion && state.SchemaVersion != legacySchemaVersion {
-		return DistributorState{}, fmt.Errorf("state schema_version must be %d", SchemaVersion)
+		return DistributorState{}, fmt.Errorf("state schema_version must be %d or %d", legacySchemaVersion, SchemaVersion)
 	}
+	legacy := state.SchemaVersion == legacySchemaVersion
 	state.DistributorVersion = raw.DistributorVersion
 	if raw.PipelineID == nil || *raw.PipelineID == "" {
 		return DistributorState{}, fmt.Errorf("state pipeline_id is required")
@@ -116,6 +152,32 @@ func parseRaw(raw rawDistributorState) (DistributorState, error) {
 		return DistributorState{}, fmt.Errorf("state published_at must be RFC3339: %w", err)
 	}
 	state.PublishedAt = publishedAt.UTC()
+	if legacy {
+		state.SchemaVersion = SchemaVersion
+		state.CreatedAt = state.PublishedAt
+		state.UpdatedAt = state.PublishedAt
+		state.State.Mode = StateModeSingleOwner
+		state.Reconciliation.Mode = config.ReconciliationModeReplace
+	} else {
+		createdAt, err := parseRequiredTime("state created_at", raw.CreatedAt)
+		if err != nil {
+			return DistributorState{}, err
+		}
+		updatedAt, err := parseRequiredTime("state updated_at", raw.UpdatedAt)
+		if err != nil {
+			return DistributorState{}, err
+		}
+		state.CreatedAt = createdAt
+		state.UpdatedAt = updatedAt
+		if raw.State == nil || raw.State.Mode == "" {
+			return DistributorState{}, fmt.Errorf("state state.mode is required")
+		}
+		state.State.Mode = raw.State.Mode
+		if raw.Reconciliation == nil || raw.Reconciliation.Mode == "" {
+			return DistributorState{}, fmt.Errorf("state reconciliation.mode is required")
+		}
+		state.Reconciliation.Mode = raw.Reconciliation.Mode
+	}
 	if raw.Source == nil || len(raw.Source.Manifest) == 0 {
 		return DistributorState{}, fmt.Errorf("state source.manifest is required")
 	}
@@ -130,7 +192,7 @@ func parseRaw(raw rawDistributorState) (DistributorState, error) {
 	if raw.Outputs == nil {
 		return DistributorState{}, fmt.Errorf("state outputs is required")
 	}
-	outputs, err := parseOutputs(raw.Outputs)
+	outputs, err := parseOutputs(raw.Outputs, legacy, state.PublishedAt)
 	if err != nil {
 		return DistributorState{}, err
 	}
@@ -138,11 +200,22 @@ func parseRaw(raw rawDistributorState) (DistributorState, error) {
 	return state, nil
 }
 
-func parseOutputs(rawOutputs []rawOutputFile) ([]OutputFile, error) {
+func parseRequiredTime(context string, raw *string) (time.Time, error) {
+	if raw == nil || *raw == "" {
+		return time.Time{}, fmt.Errorf("%s is required", context)
+	}
+	parsed, err := time.Parse(time.RFC3339, *raw)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("%s must be RFC3339: %w", context, err)
+	}
+	return parsed.UTC(), nil
+}
+
+func parseOutputs(rawOutputs []rawOutputFile, legacy bool, publishedAt time.Time) ([]OutputFile, error) {
 	outputs := make([]OutputFile, 0, len(rawOutputs))
 	seen := make(map[string]struct{}, len(rawOutputs))
 	for index, raw := range rawOutputs {
-		output, err := parseOutput(index, raw)
+		output, err := parseOutput(index, raw, legacy, publishedAt)
 		if err != nil {
 			return nil, err
 		}
@@ -155,7 +228,7 @@ func parseOutputs(rawOutputs []rawOutputFile) ([]OutputFile, error) {
 	return outputs, nil
 }
 
-func parseOutput(index int, raw rawOutputFile) (OutputFile, error) {
+func parseOutput(index int, raw rawOutputFile, legacy bool, publishedAt time.Time) (OutputFile, error) {
 	if raw.Path == nil || *raw.Path == "" {
 		return OutputFile{}, fmt.Errorf("state outputs[%d].path is required", index)
 	}
@@ -171,6 +244,19 @@ func parseOutput(index int, raw rawOutputFile) (OutputFile, error) {
 	if raw.Size == nil {
 		return OutputFile{}, fmt.Errorf("state outputs[%d].size is required", index)
 	}
+	createdAt := publishedAt
+	updatedAt := publishedAt
+	if !legacy {
+		var err error
+		createdAt, err = parseRequiredTime(fmt.Sprintf("state outputs[%d].created_at", index), raw.CreatedAt)
+		if err != nil {
+			return OutputFile{}, err
+		}
+		updatedAt, err = parseRequiredTime(fmt.Sprintf("state outputs[%d].updated_at", index), raw.UpdatedAt)
+		if err != nil {
+			return OutputFile{}, err
+		}
+	}
 	return OutputFile{
 		Path:       *raw.Path,
 		Kind:       *raw.Kind,
@@ -179,6 +265,8 @@ func parseOutput(index int, raw rawOutputFile) (OutputFile, error) {
 		URL:        raw.URL,
 		SHA256:     *raw.SHA256,
 		Size:       *raw.Size,
+		CreatedAt:  createdAt,
+		UpdatedAt:  updatedAt,
 	}, nil
 }
 
@@ -186,19 +274,39 @@ func (s DistributorState) PublishedAtString() string {
 	return s.PublishedAt.UTC().Format(time.RFC3339)
 }
 
+func (s DistributorState) CreatedAtString() string {
+	return s.CreatedAt.UTC().Format(time.RFC3339)
+}
+
+func (s DistributorState) UpdatedAtString() string {
+	return s.UpdatedAt.UTC().Format(time.RFC3339)
+}
+
+func (o OutputFile) CreatedAtString() string {
+	return o.CreatedAt.UTC().Format(time.RFC3339)
+}
+
+func (o OutputFile) UpdatedAtString() string {
+	return o.UpdatedAt.UTC().Format(time.RFC3339)
+}
+
 func (s DistributorState) MarshalJSON() ([]byte, error) {
 	type sourceJSON struct {
 		Manifest bundle.Manifest `json:"manifest"`
 	}
 	type stateJSON struct {
-		SchemaVersion      int          `json:"schema_version"`
+		SchemaVersion      int                  `json:"schema_version"`
-		DistributorVersion string       `json:"distributor_version,omitempty"`
+		DistributorVersion string               `json:"distributor_version,omitempty"`
-		PipelineID         string       `json:"pipeline_id"`
+		PipelineID         string               `json:"pipeline_id"`
-		DestinationID      string       `json:"destination_id"`
+		DestinationID      string               `json:"destination_id"`
-		PublishedAt        string       `json:"published_at"`
+		PublishedAt        string               `json:"published_at"`
-		Source             sourceJSON   `json:"source"`
+		CreatedAt          string               `json:"created_at"`
-		Links              *LinkState   `json:"links,omitempty"`
+		UpdatedAt          string               `json:"updated_at"`
-		Outputs            []OutputFile `json:"outputs"`
+		State              StatePolicy          `json:"state"`
+		Reconciliation     ReconciliationPolicy `json:"reconciliation"`
+		Source             sourceJSON           `json:"source"`
+		Links              *LinkState           `json:"links,omitempty"`
+		Outputs            []OutputFile         `json:"outputs"`
 	}
 	return json.Marshal(stateJSON{
 		SchemaVersion:      s.SchemaVersion,
@@ -206,12 +314,30 @@ func (s DistributorState) MarshalJSON() ([]byte, error) {
 		PipelineID:         s.PipelineID,
 		DestinationID:      s.DestinationID,
 		PublishedAt:        s.PublishedAtString(),
+		CreatedAt:          s.CreatedAtString(),
+		UpdatedAt:          s.UpdatedAtString(),
+		State:              s.State,
+		Reconciliation:     s.Reconciliation,
 		Source:             sourceJSON{Manifest: s.Source.Manifest},
 		Links:              s.Links,
 		Outputs:            s.Outputs,
 	})
 }
 
+func (p StatePolicy) MarshalJSON() ([]byte, error) {
+	type policyJSON struct {
+		Mode string `json:"mode"`
+	}
+	return json.Marshal(policyJSON{Mode: p.Mode})
+}
+
+func (p ReconciliationPolicy) MarshalJSON() ([]byte, error) {
+	type policyJSON struct {
+		Mode string `json:"mode"`
+	}
+	return json.Marshal(policyJSON{Mode: p.Mode})
+}
+
 func (l LinkState) MarshalJSON() ([]byte, error) {
 	type linkJSON struct {
 		PrimaryURL string `json:"primary_url,omitempty"`
@@ -228,6 +354,8 @@ func (o OutputFile) MarshalJSON() ([]byte, error) {
 		URL        string `json:"url,omitempty"`
 		SHA256     string `json:"sha256"`
 		Size       int64  `json:"size"`
+		CreatedAt  string `json:"created_at"`
+		UpdatedAt  string `json:"updated_at"`
 	}
 	return json.Marshal(outputJSON{
 		Path:       o.Path,
@@ -237,5 +365,7 @@ func (o OutputFile) MarshalJSON() ([]byte, error) {
 		URL:        o.URL,
 		SHA256:     o.SHA256,
 		Size:       o.Size,
+		CreatedAt:  o.CreatedAt.UTC().Format(time.RFC3339),
+		UpdatedAt:  o.UpdatedAt.UTC().Format(time.RFC3339),
 	})
 }

internal/state/distributor_test.go

@@ -8,6 +8,7 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
 )
 
 func TestParseValidState(t *testing.T) {
@@ -24,9 +25,24 @@ func TestParseValidState(t *testing.T) {
 	if got, want := state.PublishedAtString(), "2026-05-30T11:12:00Z"; got != want {
 		t.Fatalf("PublishedAtString() = %q, want %q", got, want)
 	}
+	if got, want := state.CreatedAtString(), "2026-05-30T11:12:00Z"; got != want {
+		t.Fatalf("CreatedAtString() = %q, want %q", got, want)
+	}
+	if got, want := state.UpdatedAtString(), "2026-05-30T11:12:00Z"; got != want {
+		t.Fatalf("UpdatedAtString() = %q, want %q", got, want)
+	}
+	if got, want := state.State.Mode, StateModeSingleOwner; got != want {
+		t.Fatalf("state mode = %q, want %q", got, want)
+	}
+	if got, want := state.Reconciliation.Mode, config.ReconciliationModeReplace; got != want {
+		t.Fatalf("reconciliation mode = %q, want %q", got, want)
+	}
 	if got, want := len(state.Outputs), 1; got != want {
 		t.Fatalf("output count = %d, want %d", got, want)
 	}
+	if got, want := state.Outputs[0].CreatedAtString(), "2026-05-30T11:12:00Z"; got != want {
+		t.Fatalf("output CreatedAtString() = %q, want %q", got, want)
+	}
 }
 
 func TestParseValidStateWithLinks(t *testing.T) {
@@ -45,6 +61,38 @@ func TestParseValidStateWithLinks(t *testing.T) {
 	}
 }
 
+func TestRemoveMissingOutputs(t *testing.T) {
+	state, err := Parse([]byte(validStateJSON(t)))
+	if err != nil {
+		t.Fatalf("Parse() error = %v", err)
+	}
+	state.Outputs = append(state.Outputs, OutputFile{
+		Path:       "summary.txt",
+		Kind:       OutputKindSource,
+		SourcePath: "summary.txt",
+		SHA256:     "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+		Size:       10,
+		CreatedAt:  state.CreatedAt,
+		UpdatedAt:  state.UpdatedAt,
+	})
+
+	next, changed := RemoveMissingOutputs(state, []string{"summary.txt"})
+	if !changed {
+		t.Fatal("RemoveMissingOutputs() changed = false, want true")
+	}
+	if got, want := ManagedOutputPaths(next), []string{"report.md"}; strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("paths = %#v, want %#v", got, want)
+	}
+
+	unchanged, changed := RemoveMissingOutputs(next, []string{"missing.txt"})
+	if changed {
+		t.Fatal("RemoveMissingOutputs() changed = true, want false")
+	}
+	if got, want := ManagedOutputPaths(unchanged), []string{"report.md"}; strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("unchanged paths = %#v, want %#v", got, want)
+	}
+}
+
 func TestParseNormalizesPublishedAtOffset(t *testing.T) {
 	body := strings.Replace(validStateJSON(t), `"published_at": "2026-05-30T11:12:00Z"`, `"published_at": "2026-05-30T13:12:00+02:00"`, 1)
 	state, err := Parse([]byte(body))
@@ -62,6 +110,10 @@ func TestParseRejectsMissingFields(t *testing.T) {
 		"pipeline_id":    `"pipeline_id"`,
 		"destination_id": `"destination_id"`,
 		"published_at":   `"published_at"`,
+		"created_at":     `"created_at"`,
+		"updated_at":     `"updated_at"`,
+		"state":          `"state"`,
+		"reconciliation": `"reconciliation"`,
 		"source":         `"source"`,
 		"outputs":        `"outputs"`,
 	}
@@ -75,9 +127,31 @@ func TestParseRejectsMissingFields(t *testing.T) {
 }
 
 func TestParseRejectsInvalidSchemaVersion(t *testing.T) {
-	body := strings.Replace(validStateJSON(t), `"schema_version": 1`, `"schema_version": 2`, 1)
+	body := strings.Replace(validStateJSON(t), `"schema_version": 2`, `"schema_version": 3`, 1)
 	_, err := Parse([]byte(body))
-	assertStateErrorContains(t, err, "schema_version must be 1")
+	assertStateErrorContains(t, err, "schema_version must be 1 or 2")
+}
+
+func TestParseLegacyStateInfersSingleOwnerDefaults(t *testing.T) {
+	state, err := Parse([]byte(legacyStateJSON(t)))
+	if err != nil {
+		t.Fatalf("Parse() error = %v", err)
+	}
+	if got, want := state.SchemaVersion, SchemaVersion; got != want {
+		t.Fatalf("schema version = %d, want normalized %d", got, want)
+	}
+	if got, want := state.CreatedAtString(), "2026-05-30T11:12:00Z"; got != want {
+		t.Fatalf("created_at = %q, want %q", got, want)
+	}
+	if got, want := state.State.Mode, StateModeSingleOwner; got != want {
+		t.Fatalf("state mode = %q, want %q", got, want)
+	}
+	if got, want := state.Reconciliation.Mode, config.ReconciliationModeReplace; got != want {
+		t.Fatalf("reconciliation mode = %q, want %q", got, want)
+	}
+	if got, want := state.Outputs[0].UpdatedAtString(), "2026-05-30T11:12:00Z"; got != want {
+		t.Fatalf("output updated_at = %q, want %q", got, want)
+	}
 }
 
 func TestParseRejectsInvalidEmbeddedManifest(t *testing.T) {
@@ -161,6 +235,12 @@ func TestParseRejectsInvalidOutputMetadata(t *testing.T) {
 		"negative size": func(s *DistributorState) {
 			s.Outputs[0].Size = -1
 		},
+		"missing output created_at": func(s *DistributorState) {
+			s.Outputs[0].CreatedAt = time.Time{}
+		},
+		"missing output updated_at": func(s *DistributorState) {
+			s.Outputs[0].UpdatedAt = time.Time{}
+		},
 		"invalid output url": func(s *DistributorState) {
 			s.Outputs[0].URL = "file:///tmp/report.md"
 		},
@@ -202,20 +282,33 @@ func TestParseRejectsMalformedPublishedTimestamp(t *testing.T) {
 	assertStateErrorContains(t, err, "published_at must be RFC3339")
 }
 
+func TestParseRejectsMalformedCreatedTimestamp(t *testing.T) {
+	body := strings.Replace(validStateJSON(t), `"created_at": "2026-05-30T11:12:00Z"`, `"created_at": "May 30"`, 1)
+	_, err := Parse([]byte(body))
+	assertStateErrorContains(t, err, "created_at must be RFC3339")
+}
+
 func TestMarshalNormalizesPublishedAtUTC(t *testing.T) {
 	source := validManifest(t)
+	publishedAt := time.Date(2026, 5, 30, 13, 12, 0, 0, time.FixedZone("offset", 2*60*60))
 	state := DistributorState{
-		SchemaVersion: SchemaVersion,
+		SchemaVersion:  SchemaVersion,
-		PipelineID:    "reports",
+		PipelineID:     "reports",
-		DestinationID: "archive",
+		DestinationID:  "archive",
-		PublishedAt:   time.Date(2026, 5, 30, 13, 12, 0, 0, time.FixedZone("offset", 2*60*60)),
+		PublishedAt:    publishedAt,
-		Source:        SourceState{Manifest: source},
+		CreatedAt:      publishedAt,
+		UpdatedAt:      publishedAt,
+		State:          StatePolicy{Mode: StateModeSingleOwner},
+		Reconciliation: ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
+		Source:         SourceState{Manifest: source},
 		Outputs: []OutputFile{{
 			Path:       "report.md",
 			Kind:       OutputKindSource,
 			SourcePath: "report.md",
 			SHA256:     source.Files[0].SHA256,
 			Size:       source.Files[0].Size,
+			CreatedAt:  publishedAt,
+			UpdatedAt:  publishedAt,
 		}},
 	}
 	data, err := json.Marshal(state)
@@ -229,13 +322,18 @@ func TestMarshalNormalizesPublishedAtUTC(t *testing.T) {
 
 func TestMarshalIncludesLinksWhenPresent(t *testing.T) {
 	source := validManifest(t)
+	publishedAt := time.Date(2026, 5, 30, 11, 12, 0, 0, time.UTC)
 	state := DistributorState{
-		SchemaVersion: SchemaVersion,
+		SchemaVersion:  SchemaVersion,
-		PipelineID:    "reports",
+		PipelineID:     "reports",
-		DestinationID: "archive",
+		DestinationID:  "archive",
-		PublishedAt:   time.Date(2026, 5, 30, 11, 12, 0, 0, time.UTC),
+		PublishedAt:    publishedAt,
-		Source:        SourceState{Manifest: source},
+		CreatedAt:      publishedAt,
-		Links:         &LinkState{PrimaryURL: "https://reports.example.com/archive/report.md"},
+		UpdatedAt:      publishedAt,
+		State:          StatePolicy{Mode: StateModeSingleOwner},
+		Reconciliation: ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
+		Source:         SourceState{Manifest: source},
+		Links:          &LinkState{PrimaryURL: "https://reports.example.com/archive/report.md"},
 		Outputs: []OutputFile{{
 			Path:       "report.md",
 			Kind:       OutputKindSource,
@@ -243,6 +341,8 @@ func TestMarshalIncludesLinksWhenPresent(t *testing.T) {
 			URL:        "https://reports.example.com/archive/report.md",
 			SHA256:     source.Files[0].SHA256,
 			Size:       source.Files[0].Size,
+			CreatedAt:  publishedAt,
+			UpdatedAt:  publishedAt,
 		}},
 	}
 	data, err := json.Marshal(state)
@@ -257,6 +357,42 @@ func TestMarshalIncludesLinksWhenPresent(t *testing.T) {
 	}
 }
 
+func TestOutputHelpers(t *testing.T) {
+	createdAt := time.Date(2026, 5, 30, 11, 12, 0, 0, time.UTC)
+	updatedAt := createdAt.Add(time.Hour)
+	retained := []OutputFile{{
+		Path:      "old.md",
+		Kind:      OutputKindSource,
+		CreatedAt: createdAt,
+		UpdatedAt: createdAt,
+	}, {
+		Path:      "report.md",
+		Kind:      OutputKindSource,
+		CreatedAt: createdAt,
+		UpdatedAt: createdAt,
+	}}
+	projected := ProjectOutputs([]OutputProjection{{
+		Path: "report.md",
+		Kind: OutputKindSource,
+	}, {
+		Path: "new.md",
+		Kind: OutputKindSource,
+	}}, retained, updatedAt)
+	if got, ok := FindOutputByPath(projected, "report.md"); !ok || !got.CreatedAt.Equal(createdAt) || !got.UpdatedAt.Equal(updatedAt) {
+		t.Fatalf("projected report.md = %#v, want preserved created_at and updated updated_at", got)
+	}
+	merged, err := MergeOutputFiles(retained, projected)
+	if err != nil {
+		t.Fatalf("MergeOutputFiles() error = %v", err)
+	}
+	if got, want := len(merged), 3; got != want {
+		t.Fatalf("merged count = %d, want %d", got, want)
+	}
+	if got, want := ManagedOutputPaths(DistributorState{Outputs: merged}), []string{"old.md", "report.md", "new.md"}; strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("managed paths = %#v, want %#v", got, want)
+	}
+}
+
 func validStateJSON(t *testing.T) string {
 	t.Helper()
 	return validStateWithManifestJSON(t, manifestJSON(t))
@@ -265,11 +401,15 @@ func validStateJSON(t *testing.T) string {
 func validStateWithManifestJSON(t *testing.T, manifest string) string {
 	t.Helper()
 	return `{
-  "schema_version": 1,
+  "schema_version": 2,
   "distributor_version": "dev",
   "pipeline_id": "reports",
   "destination_id": "archive",
   "published_at": "2026-05-30T11:12:00Z",
+  "created_at": "2026-05-30T11:12:00Z",
+  "updated_at": "2026-05-30T11:12:00Z",
+  "state": {"mode": "single_owner"},
+  "reconciliation": {"mode": "replace"},
   "source": {
     "manifest": ` + manifest + `
   },
@@ -279,12 +419,31 @@ func validStateWithManifestJSON(t *testing.T, manifest string) string {
       "kind": "source",
       "source_path": "report.md",
       "sha256": "sha256:3640fd37140ee4d2e0e93e78834f232ea67a50e7bc6279203690cc7de1975fa6",
-      "size": 16
+      "size": 16,
+      "created_at": "2026-05-30T11:12:00Z",
+      "updated_at": "2026-05-30T11:12:00Z"
     }
   ]
 }`
 }
 
+func legacyStateJSON(t *testing.T) string {
+	t.Helper()
+	return strings.Replace(strings.Replace(strings.Replace(strings.Replace(strings.Replace(strings.Replace(validStateJSON(t),
+		`"schema_version": 2`, `"schema_version": 1`, 1),
+		`  "created_at": "2026-05-30T11:12:00Z",
+`, "", 1),
+		`  "updated_at": "2026-05-30T11:12:00Z",
+`, "", 1),
+		`  "state": {"mode": "single_owner"},
+`, "", 1),
+		`  "reconciliation": {"mode": "replace"},
+`, "", 1),
+		`,
+      "created_at": "2026-05-30T11:12:00Z",
+      "updated_at": "2026-05-30T11:12:00Z"`, "", 1)
+}
+
 func manifestJSON(t *testing.T) string {
 	t.Helper()
 	data, err := os.ReadFile("../bundle/testdata/valid_bundle/manifest.json")

internal/state/outputs.go

@@ -0,0 +1,330 @@
+package state
+
+import (
+	"fmt"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+)
+
+type OutputProjection struct {
+	Path       string
+	Kind       string
+	SourcePath string
+	Transform  string
+	URL        string
+	SHA256     string
+	Size       int64
+}
+
+func FindOutputByPath(outputs []OutputFile, path string) (OutputFile, bool) {
+	for _, output := range outputs {
+		if output.Path == path {
+			return output, true
+		}
+	}
+	return OutputFile{}, false
+}
+
+func MergeOutputFiles(retained, planned []OutputFile) ([]OutputFile, error) {
+	outputs := make([]OutputFile, 0, len(retained)+len(planned))
+	indexByPath := make(map[string]int, len(retained)+len(planned))
+	for _, output := range retained {
+		if _, exists := indexByPath[output.Path]; exists {
+			return nil, fmt.Errorf("state output path %q is duplicated", output.Path)
+		}
+		indexByPath[output.Path] = len(outputs)
+		outputs = append(outputs, output)
+	}
+	seenPlanned := make(map[string]struct{}, len(planned))
+	for _, output := range planned {
+		if _, exists := seenPlanned[output.Path]; exists {
+			return nil, fmt.Errorf("state output path %q is duplicated", output.Path)
+		}
+		seenPlanned[output.Path] = struct{}{}
+		if index, exists := indexByPath[output.Path]; exists {
+			outputs[index] = output
+			continue
+		}
+		indexByPath[output.Path] = len(outputs)
+		outputs = append(outputs, output)
+	}
+	return outputs, nil
+}
+
+func ManagedOutputPaths(s DistributorState) []string {
+	paths := make([]string, 0, len(s.Outputs))
+	for _, output := range s.Outputs {
+		paths = append(paths, output.Path)
+	}
+	return paths
+}
+
+func RemoveMissingOutputs(s DistributorState, missingPaths []string) (DistributorState, bool) {
+	if len(missingPaths) == 0 {
+		return s, false
+	}
+	missing := pathSet(missingPaths)
+	next := s
+	next.Outputs = make([]OutputFile, 0, len(s.Outputs))
+	changed := false
+	for _, output := range s.Outputs {
+		if _, remove := missing[output.Path]; remove {
+			changed = true
+			continue
+		}
+		next.Outputs = append(next.Outputs, output)
+	}
+	return next, changed
+}
+
+func ProjectOutputs(outputs []OutputProjection, existing []OutputFile, now time.Time) []OutputFile {
+	now = now.UTC()
+	files := make([]OutputFile, 0, len(outputs))
+	for _, output := range outputs {
+		createdAt := now
+		if existingOutput, ok := FindOutputByPath(existing, output.Path); ok {
+			createdAt = existingOutput.CreatedAt
+		}
+		files = append(files, OutputFile{
+			Path:       output.Path,
+			Kind:       output.Kind,
+			SourcePath: output.SourcePath,
+			Transform:  output.Transform,
+			URL:        output.URL,
+			SHA256:     output.SHA256,
+			Size:       output.Size,
+			CreatedAt:  createdAt,
+			UpdatedAt:  now,
+		})
+	}
+	return files
+}
+
+func CurrentOwnerScope(pipelineID, destinationID string) OwnerScope {
+	return OwnerScope{PipelineID: pipelineID, DestinationID: destinationID}
+}
+
+func (s SharedRootState) Owner(scope OwnerScope) (OwnerRecord, bool) {
+	for _, owner := range s.Owners {
+		if owner.Scope == scope {
+			return owner, true
+		}
+	}
+	return OwnerRecord{}, false
+}
+
+func (s SharedRootState) SourceManifest(scope OwnerScope) (bundle.Manifest, bool) {
+	owner, ok := s.Owner(scope)
+	if !ok {
+		return bundle.Manifest{}, false
+	}
+	return owner.Source.Manifest, true
+}
+
+func (s SharedRootState) ManagedOutputPaths(scope OwnerScope) []string {
+	paths := make([]string, 0, len(s.Outputs))
+	for _, output := range s.Outputs {
+		if output.Owner == scope {
+			paths = append(paths, output.Path)
+		}
+	}
+	return paths
+}
+
+func (s SharedRootState) AllManagedOutputPaths() []string {
+	paths := make([]string, 0, len(s.Outputs))
+	for _, output := range s.Outputs {
+		paths = append(paths, output.Path)
+	}
+	return paths
+}
+
+func RemoveMissingSharedRootOwnerOutputs(s SharedRootState, scope OwnerScope, missingPaths []string) (SharedRootState, bool) {
+	if len(missingPaths) == 0 {
+		return s, false
+	}
+	missing := pathSet(missingPaths)
+	next := s
+	next.Outputs = make([]SharedRootOutputFile, 0, len(s.Outputs))
+	changed := false
+	for _, output := range s.Outputs {
+		if output.Owner == scope {
+			if _, remove := missing[output.Path]; remove {
+				changed = true
+				continue
+			}
+		}
+		next.Outputs = append(next.Outputs, output)
+	}
+	return next, changed
+}
+
+func RemoveMissingSharedRootOutputs(s SharedRootState, missingPaths []string) (SharedRootState, bool) {
+	if len(missingPaths) == 0 {
+		return s, false
+	}
+	missing := pathSet(missingPaths)
+	next := s
+	next.Outputs = make([]SharedRootOutputFile, 0, len(s.Outputs))
+	changed := false
+	for _, output := range s.Outputs {
+		if _, remove := missing[output.Path]; remove {
+			changed = true
+			continue
+		}
+		next.Outputs = append(next.Outputs, output)
+	}
+	return next, changed
+}
+
+func (s SharedRootState) OutputOwner(path string) (OwnerScope, bool) {
+	for _, output := range s.Outputs {
+		if output.Path == path {
+			return output.Owner, true
+		}
+	}
+	return OwnerScope{}, false
+}
+
+func (s SharedRootState) PathOwnershipConflict(scope OwnerScope, paths []string) (PathOwnershipConflict, bool) {
+	for _, path := range paths {
+		owner, exists := s.OutputOwner(path)
+		if exists && owner != scope {
+			return PathOwnershipConflict{Path: path, Owner: owner}, true
+		}
+	}
+	return PathOwnershipConflict{}, false
+}
+
+func ProjectSharedRootOutputs(outputs []OutputProjection, existing []SharedRootOutputFile, scope OwnerScope, source bundle.Manifest, now time.Time) []SharedRootOutputFile {
+	now = now.UTC()
+	files := make([]SharedRootOutputFile, 0, len(outputs))
+	for _, output := range outputs {
+		createdAt := now
+		if existingOutput, ok := findSharedRootOutput(existing, output.Path); ok && existingOutput.Owner == scope {
+			createdAt = existingOutput.CreatedAt
+		}
+		files = append(files, SharedRootOutputFile{
+			Path:          output.Path,
+			Kind:          output.Kind,
+			SourcePath:    output.SourcePath,
+			Transform:     output.Transform,
+			URL:           output.URL,
+			SHA256:        output.SHA256,
+			Size:          output.Size,
+			Owner:         scope,
+			SourceID:      source.ID,
+			SourceDigest:  source.Digest,
+			SourceCreated: source.Created,
+			CreatedAt:     createdAt,
+			UpdatedAt:     now,
+		})
+	}
+	return files
+}
+
+func ReplaceOwnerOutputs(s SharedRootState, scope OwnerScope, owner OwnerRecord, planned []SharedRootOutputFile) (SharedRootState, error) {
+	if conflict, ok := s.PathOwnershipConflict(scope, sharedRootOutputPaths(planned)); ok {
+		return SharedRootState{}, fmt.Errorf("state output path %q is owned by %s/%s", conflict.Path, conflict.Owner.PipelineID, conflict.Owner.DestinationID)
+	}
+	if err := validatePlannedSharedRootOutputs(scope, planned); err != nil {
+		return SharedRootState{}, err
+	}
+	next := s
+	next.Owners = upsertOwner(s.Owners, owner)
+	next.Outputs = make([]SharedRootOutputFile, 0, len(s.Outputs)+len(planned))
+	for _, output := range s.Outputs {
+		if output.Owner != scope {
+			next.Outputs = append(next.Outputs, output)
+		}
+	}
+	next.Outputs = append(next.Outputs, planned...)
+	return next, nil
+}
+
+func MergeOwnerOutputs(s SharedRootState, scope OwnerScope, owner OwnerRecord, planned []SharedRootOutputFile) (SharedRootState, error) {
+	if conflict, ok := s.PathOwnershipConflict(scope, sharedRootOutputPaths(planned)); ok {
+		return SharedRootState{}, fmt.Errorf("state output path %q is owned by %s/%s", conflict.Path, conflict.Owner.PipelineID, conflict.Owner.DestinationID)
+	}
+	if err := validatePlannedSharedRootOutputs(scope, planned); err != nil {
+		return SharedRootState{}, err
+	}
+	next := s
+	next.Owners = upsertOwner(s.Owners, owner)
+	outputs := make([]SharedRootOutputFile, 0, len(s.Outputs)+len(planned))
+	indexByPath := make(map[string]int, len(s.Outputs)+len(planned))
+	for _, output := range s.Outputs {
+		indexByPath[output.Path] = len(outputs)
+		outputs = append(outputs, output)
+	}
+	for _, output := range planned {
+		if index, exists := indexByPath[output.Path]; exists {
+			outputs[index] = output
+			continue
+		}
+		indexByPath[output.Path] = len(outputs)
+		outputs = append(outputs, output)
+	}
+	next.Outputs = outputs
+	return next, nil
+}
+
+func findSharedRootOutput(outputs []SharedRootOutputFile, path string) (SharedRootOutputFile, bool) {
+	for _, output := range outputs {
+		if output.Path == path {
+			return output, true
+		}
+	}
+	return SharedRootOutputFile{}, false
+}
+
+func sharedRootOutputPaths(outputs []SharedRootOutputFile) []string {
+	paths := make([]string, 0, len(outputs))
+	for _, output := range outputs {
+		paths = append(paths, output.Path)
+	}
+	return paths
+}
+
+func rejectDuplicateSharedRootOutputs(outputs []SharedRootOutputFile) error {
+	seen := make(map[string]struct{}, len(outputs))
+	for _, output := range outputs {
+		if _, exists := seen[output.Path]; exists {
+			return fmt.Errorf("state output path %q is duplicated", output.Path)
+		}
+		seen[output.Path] = struct{}{}
+	}
+	return nil
+}
+
+func validatePlannedSharedRootOutputs(scope OwnerScope, outputs []SharedRootOutputFile) error {
+	if err := rejectDuplicateSharedRootOutputs(outputs); err != nil {
+		return err
+	}
+	for _, output := range outputs {
+		if output.Owner != scope {
+			return fmt.Errorf("state output path %q is owned by %s/%s, not %s/%s", output.Path, output.Owner.PipelineID, output.Owner.DestinationID, scope.PipelineID, scope.DestinationID)
+		}
+	}
+	return nil
+}
+
+func upsertOwner(owners []OwnerRecord, owner OwnerRecord) []OwnerRecord {
+	next := append([]OwnerRecord(nil), owners...)
+	for index, existing := range next {
+		if existing.Scope == owner.Scope {
+			next[index] = owner
+			return next
+		}
+	}
+	return append(next, owner)
+}
+
+func pathSet(paths []string) map[string]struct{} {
+	set := make(map[string]struct{}, len(paths))
+	for _, path := range paths {
+		set[path] = struct{}{}
+	}
+	return set
+}

internal/state/prune.go

@@ -0,0 +1,121 @@
+package state
+
+import (
+	"sort"
+	"time"
+)
+
+type PruneCandidate struct {
+	Path      string
+	UpdatedAt time.Time
+	Owner     *OwnerScope
+}
+
+type PrunePlanOptions struct {
+	Now        time.Time
+	OlderThan  *time.Duration
+	KeepLatest *int
+}
+
+type PrunePlan struct {
+	Pruned    []PruneCandidate
+	Preserved []PruneCandidate
+}
+
+func SingleOwnerPruneCandidates(s DistributorState) []PruneCandidate {
+	candidates := make([]PruneCandidate, 0, len(s.Outputs))
+	for _, output := range s.Outputs {
+		candidates = append(candidates, PruneCandidate{
+			Path:      output.Path,
+			UpdatedAt: output.UpdatedAt,
+		})
+	}
+	return candidates
+}
+
+func SharedRootPruneCandidates(s SharedRootState, scope OwnerScope) []PruneCandidate {
+	candidates := make([]PruneCandidate, 0, len(s.Outputs))
+	for _, output := range s.Outputs {
+		if output.Owner != scope {
+			continue
+		}
+		owner := output.Owner
+		candidates = append(candidates, PruneCandidate{
+			Path:      output.Path,
+			UpdatedAt: output.UpdatedAt,
+			Owner:     &owner,
+		})
+	}
+	return candidates
+}
+
+func PlanPrune(candidates []PruneCandidate, options PrunePlanOptions) PrunePlan {
+	ordered := append([]PruneCandidate(nil), candidates...)
+	sortPruneCandidatesNewestFirst(ordered)
+	if options.OlderThan == nil && options.KeepLatest == nil {
+		return PrunePlan{
+			Pruned:    []PruneCandidate{},
+			Preserved: ordered,
+		}
+	}
+
+	preservedByPath := make(map[string]struct{})
+	if options.KeepLatest != nil {
+		keep := *options.KeepLatest
+		if keep < 0 {
+			keep = 0
+		}
+		if keep > len(ordered) {
+			keep = len(ordered)
+		}
+		for _, candidate := range ordered[:keep] {
+			preservedByPath[candidate.Path] = struct{}{}
+		}
+	}
+
+	plan := PrunePlan{
+		Pruned:    []PruneCandidate{},
+		Preserved: []PruneCandidate{},
+	}
+	cutoff := time.Time{}
+	if options.OlderThan != nil {
+		now := options.Now.UTC()
+		if now.IsZero() {
+			now = time.Now().UTC()
+		}
+		cutoff = now.Add(-*options.OlderThan)
+	}
+
+	for _, candidate := range ordered {
+		if _, preserved := preservedByPath[candidate.Path]; preserved {
+			plan.Preserved = append(plan.Preserved, candidate)
+			continue
+		}
+		if options.OlderThan == nil || candidate.UpdatedAt.Before(cutoff) {
+			plan.Pruned = append(plan.Pruned, candidate)
+			continue
+		}
+		plan.Preserved = append(plan.Preserved, candidate)
+	}
+	sortPruneCandidatesOldestFirst(plan.Pruned)
+	sortPruneCandidatesNewestFirst(plan.Preserved)
+	return plan
+}
+
+func sortPruneCandidatesNewestFirst(candidates []PruneCandidate) {
+	sort.Slice(candidates, func(i, j int) bool {
+		if !candidates[i].UpdatedAt.Equal(candidates[j].UpdatedAt) {
+			return candidates[i].UpdatedAt.After(candidates[j].UpdatedAt)
+		}
+		return candidates[i].Path < candidates[j].Path
+	})
+}
+
+func sortPruneCandidatesOldestFirst(candidates []PruneCandidate) {
+	sort.Slice(candidates, func(i, j int) bool {
+		if !candidates[i].UpdatedAt.Equal(candidates[j].UpdatedAt) {
+			return candidates[i].UpdatedAt.Before(candidates[j].UpdatedAt)
+		}
+		return candidates[i].Path < candidates[j].Path
+	})
+}

internal/state/prune_test.go

@@ -0,0 +1,96 @@
+package state
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestPlanPruneOlderThan(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	olderThan := 48 * time.Hour
+	plan := PlanPrune([]PruneCandidate{
+		{Path: "old.txt", UpdatedAt: now.Add(-72 * time.Hour)},
+		{Path: "fresh.txt", UpdatedAt: now.Add(-24 * time.Hour)},
+	}, PrunePlanOptions{Now: now, OlderThan: &olderThan})
+
+	if got, want := pruneCandidatePaths(plan.Pruned), "old.txt"; got != want {
+		t.Fatalf("pruned = %q, want %q", got, want)
+	}
+	if got, want := pruneCandidatePaths(plan.Preserved), "fresh.txt"; got != want {
+		t.Fatalf("preserved = %q, want %q", got, want)
+	}
+}
+
+func TestPlanPruneKeepLatest(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	keepLatest := 2
+	plan := PlanPrune([]PruneCandidate{
+		{Path: "old.txt", UpdatedAt: now.Add(-72 * time.Hour)},
+		{Path: "new.txt", UpdatedAt: now.Add(-1 * time.Hour)},
+		{Path: "middle.txt", UpdatedAt: now.Add(-24 * time.Hour)},
+	}, PrunePlanOptions{KeepLatest: &keepLatest})
+
+	if got, want := pruneCandidatePaths(plan.Pruned), "old.txt"; got != want {
+		t.Fatalf("pruned = %q, want %q", got, want)
+	}
+	if got, want := pruneCandidatePaths(plan.Preserved), "new.txt,middle.txt"; got != want {
+		t.Fatalf("preserved = %q, want %q", got, want)
+	}
+}
+
+func TestPlanPruneCombinedPolicyPreservesLatestBeforeAgeCheck(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	olderThan := 48 * time.Hour
+	keepLatest := 1
+	plan := PlanPrune([]PruneCandidate{
+		{Path: "oldest.txt", UpdatedAt: now.Add(-96 * time.Hour)},
+		{Path: "old.txt", UpdatedAt: now.Add(-72 * time.Hour)},
+		{Path: "fresh.txt", UpdatedAt: now.Add(-24 * time.Hour)},
+	}, PrunePlanOptions{Now: now, OlderThan: &olderThan, KeepLatest: &keepLatest})
+
+	if got, want := pruneCandidatePaths(plan.Pruned), "oldest.txt,old.txt"; got != want {
+		t.Fatalf("pruned = %q, want %q", got, want)
+	}
+	if got, want := pruneCandidatePaths(plan.Preserved), "fresh.txt"; got != want {
+		t.Fatalf("preserved = %q, want %q", got, want)
+	}
+}
+
+func TestPlanPruneDeterministicTieBreaking(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	keepLatest := 1
+	plan := PlanPrune([]PruneCandidate{
+		{Path: "b.txt", UpdatedAt: now},
+		{Path: "a.txt", UpdatedAt: now},
+		{Path: "c.txt", UpdatedAt: now.Add(-time.Hour)},
+	}, PrunePlanOptions{KeepLatest: &keepLatest})
+
+	if got, want := pruneCandidatePaths(plan.Preserved), "a.txt"; got != want {
+		t.Fatalf("preserved = %q, want %q", got, want)
+	}
+	if got, want := pruneCandidatePaths(plan.Pruned), "c.txt,b.txt"; got != want {
+		t.Fatalf("pruned = %q, want %q", got, want)
+	}
+}
+
+func TestSharedRootPruneCandidatesPreserveOtherOwners(t *testing.T) {
+	sharedRoot := validSharedRootState(t)
+	scope := CurrentOwnerScope("reports", "archive")
+	candidates := SharedRootPruneCandidates(sharedRoot, scope)
+
+	if got, want := pruneCandidatePaths(candidates), "report.md"; got != want {
+		t.Fatalf("candidates = %q, want %q", got, want)
+	}
+	if candidates[0].Owner == nil || *candidates[0].Owner != scope {
+		t.Fatalf("candidate owner = %#v, want current owner", candidates[0].Owner)
+	}
+}
+
+func pruneCandidatePaths(candidates []PruneCandidate) string {
+	paths := make([]string, 0, len(candidates))
+	for _, candidate := range candidates {
+		paths = append(paths, candidate.Path)
+	}
+	return strings.Join(paths, ",")
+}

internal/state/shared_root.go

@@ -0,0 +1,519 @@
+package state
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+	"gitea.maximumdirect.net/eric/distributor/internal/link"
+	"gitea.maximumdirect.net/eric/distributor/internal/storage"
+)
+
+type StateDocument struct {
+	SingleOwner *DistributorState
+	SharedRoot  *SharedRootState
+}
+
+type SharedRootState struct {
+	SchemaVersion      int
+	DistributorVersion string
+	CreatedAt          time.Time
+	UpdatedAt          time.Time
+	State              StatePolicy
+	Owners             []OwnerRecord
+	Outputs            []SharedRootOutputFile
+}
+
+type OwnerScope struct {
+	PipelineID    string
+	DestinationID string
+}
+
+type OwnerRecord struct {
+	Scope          OwnerScope
+	Reconciliation ReconciliationPolicy
+	Source         SourceState
+	Links          *LinkState
+}
+
+type SharedRootOutputFile struct {
+	Path          string
+	Kind          string
+	SourcePath    string
+	Transform     string
+	URL           string
+	SHA256        string
+	Size          int64
+	Owner         OwnerScope
+	SourceID      string
+	SourceDigest  string
+	SourceCreated time.Time
+	CreatedAt     time.Time
+	UpdatedAt     time.Time
+}
+
+type PathOwnershipConflict struct {
+	Path  string
+	Owner OwnerScope
+}
+
+type rawSharedRootState struct {
+	SchemaVersion      *int                  `json:"schema_version"`
+	DistributorVersion string                `json:"distributor_version"`
+	CreatedAt          *string               `json:"created_at"`
+	UpdatedAt          *string               `json:"updated_at"`
+	State              *rawStatePolicy       `json:"state"`
+	Owners             []rawOwnerRecord      `json:"owners"`
+	Outputs            []rawSharedRootOutput `json:"outputs"`
+}
+
+type rawOwnerRecord struct {
+	PipelineID     *string                  `json:"pipeline_id"`
+	DestinationID  *string                  `json:"destination_id"`
+	Reconciliation *rawReconciliationPolicy `json:"reconciliation"`
+	Source         *rawSourceState          `json:"source"`
+	Links          *rawLinkState            `json:"links"`
+}
+
+type rawSharedRootOutput struct {
+	Path          *string `json:"path"`
+	Kind          *string `json:"kind"`
+	SourcePath    *string `json:"source_path"`
+	Transform     string  `json:"transform"`
+	URL           string  `json:"url"`
+	SHA256        *string `json:"sha256"`
+	Size          *int64  `json:"size"`
+	PipelineID    *string `json:"pipeline_id"`
+	DestinationID *string `json:"destination_id"`
+	SourceID      *string `json:"source_id"`
+	SourceDigest  *string `json:"source_digest"`
+	SourceCreated *string `json:"source_created"`
+	CreatedAt     *string `json:"created_at"`
+	UpdatedAt     *string `json:"updated_at"`
+}
+
+func ParseDocument(data []byte) (StateDocument, error) {
+	schemaVersion, err := parseSchemaVersion(data)
+	if err != nil {
+		return StateDocument{}, err
+	}
+	if schemaVersion == SharedRootSchemaVersion {
+		sharedRoot, err := ParseSharedRoot(data)
+		if err != nil {
+			return StateDocument{}, err
+		}
+		return StateDocument{SharedRoot: &sharedRoot}, nil
+	}
+	singleOwner, err := Parse(data)
+	if err != nil {
+		return StateDocument{}, err
+	}
+	return StateDocument{SingleOwner: &singleOwner}, nil
+}
+
+func parseSchemaVersion(data []byte) (int, error) {
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	var raw struct {
+		SchemaVersion *int `json:"schema_version"`
+	}
+	if err := decoder.Decode(&raw); err != nil {
+		return 0, fmt.Errorf("parse distributor state: %w", err)
+	}
+	if raw.SchemaVersion == nil {
+		return 0, fmt.Errorf("state schema_version is required")
+	}
+	return *raw.SchemaVersion, nil
+}
+
+func ParseSharedRoot(data []byte) (SharedRootState, error) {
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	var raw rawSharedRootState
+	if err := decoder.Decode(&raw); err != nil {
+		return SharedRootState{}, fmt.Errorf("parse distributor state: %w", err)
+	}
+	var extra any
+	if err := decoder.Decode(&extra); err != io.EOF {
+		return SharedRootState{}, fmt.Errorf("parse distributor state: trailing data")
+	}
+	state, err := parseSharedRootRaw(raw)
+	if err != nil {
+		return SharedRootState{}, err
+	}
+	if err := ValidateSharedRoot(state); err != nil {
+		return SharedRootState{}, err
+	}
+	return state, nil
+}
+
+func parseSharedRootRaw(raw rawSharedRootState) (SharedRootState, error) {
+	if raw.SchemaVersion == nil {
+		return SharedRootState{}, fmt.Errorf("state schema_version is required")
+	}
+	state := SharedRootState{SchemaVersion: *raw.SchemaVersion}
+	if state.SchemaVersion != SharedRootSchemaVersion {
+		return SharedRootState{}, fmt.Errorf("state schema_version must be %d", SharedRootSchemaVersion)
+	}
+	state.DistributorVersion = raw.DistributorVersion
+	createdAt, err := parseRequiredTime("state created_at", raw.CreatedAt)
+	if err != nil {
+		return SharedRootState{}, err
+	}
+	updatedAt, err := parseRequiredTime("state updated_at", raw.UpdatedAt)
+	if err != nil {
+		return SharedRootState{}, err
+	}
+	state.CreatedAt = createdAt
+	state.UpdatedAt = updatedAt
+	if raw.State == nil || raw.State.Mode == "" {
+		return SharedRootState{}, fmt.Errorf("state state.mode is required")
+	}
+	state.State.Mode = raw.State.Mode
+	if raw.Owners == nil {
+		return SharedRootState{}, fmt.Errorf("state owners is required")
+	}
+	owners, err := parseOwnerRecords(raw.Owners)
+	if err != nil {
+		return SharedRootState{}, err
+	}
+	state.Owners = owners
+	if raw.Outputs == nil {
+		return SharedRootState{}, fmt.Errorf("state outputs is required")
+	}
+	outputs, err := parseSharedRootOutputs(raw.Outputs)
+	if err != nil {
+		return SharedRootState{}, err
+	}
+	state.Outputs = outputs
+	return state, nil
+}
+
+func parseOwnerRecords(rawOwners []rawOwnerRecord) ([]OwnerRecord, error) {
+	owners := make([]OwnerRecord, 0, len(rawOwners))
+	for index, raw := range rawOwners {
+		owner, err := parseOwnerRecord(index, raw)
+		if err != nil {
+			return nil, err
+		}
+		owners = append(owners, owner)
+	}
+	return owners, nil
+}
+
+func parseOwnerRecord(index int, raw rawOwnerRecord) (OwnerRecord, error) {
+	if raw.PipelineID == nil || *raw.PipelineID == "" {
+		return OwnerRecord{}, fmt.Errorf("state owners[%d].pipeline_id is required", index)
+	}
+	if raw.DestinationID == nil || *raw.DestinationID == "" {
+		return OwnerRecord{}, fmt.Errorf("state owners[%d].destination_id is required", index)
+	}
+	if raw.Reconciliation == nil || raw.Reconciliation.Mode == "" {
+		return OwnerRecord{}, fmt.Errorf("state owners[%d].reconciliation.mode is required", index)
+	}
+	if raw.Source == nil || len(raw.Source.Manifest) == 0 {
+		return OwnerRecord{}, fmt.Errorf("state owners[%d].source.manifest is required", index)
+	}
+	manifest, err := bundle.ParseManifest(raw.Source.Manifest)
+	if err != nil {
+		return OwnerRecord{}, fmt.Errorf("state owners[%d].source.manifest: %w", index, err)
+	}
+	owner := OwnerRecord{
+		Scope: OwnerScope{
+			PipelineID:    *raw.PipelineID,
+			DestinationID: *raw.DestinationID,
+		},
+		Reconciliation: ReconciliationPolicy{Mode: raw.Reconciliation.Mode},
+		Source:         SourceState{Manifest: manifest},
+	}
+	if raw.Links != nil {
+		owner.Links = &LinkState{PrimaryURL: raw.Links.PrimaryURL}
+	}
+	return owner, nil
+}
+
+func parseSharedRootOutputs(rawOutputs []rawSharedRootOutput) ([]SharedRootOutputFile, error) {
+	outputs := make([]SharedRootOutputFile, 0, len(rawOutputs))
+	for index, raw := range rawOutputs {
+		output, err := parseSharedRootOutput(index, raw)
+		if err != nil {
+			return nil, err
+		}
+		outputs = append(outputs, output)
+	}
+	return outputs, nil
+}
+
+func parseSharedRootOutput(index int, raw rawSharedRootOutput) (SharedRootOutputFile, error) {
+	if raw.Path == nil || *raw.Path == "" {
+		return SharedRootOutputFile{}, fmt.Errorf("state outputs[%d].path is required", index)
+	}
+	if raw.Kind == nil || *raw.Kind == "" {
+		return SharedRootOutputFile{}, fmt.Errorf("state outputs[%d].kind is required", index)
+	}
+	if raw.SourcePath == nil || *raw.SourcePath == "" {
+		return SharedRootOutputFile{}, fmt.Errorf("state outputs[%d].source_path is required", index)
+	}
+	if raw.SHA256 == nil || *raw.SHA256 == "" {
+		return SharedRootOutputFile{}, fmt.Errorf("state outputs[%d].sha256 is required", index)
+	}
+	if raw.Size == nil {
+		return SharedRootOutputFile{}, fmt.Errorf("state outputs[%d].size is required", index)
+	}
+	if raw.PipelineID == nil || *raw.PipelineID == "" {
+		return SharedRootOutputFile{}, fmt.Errorf("state outputs[%d].pipeline_id is required", index)
+	}
+	if raw.DestinationID == nil || *raw.DestinationID == "" {
+		return SharedRootOutputFile{}, fmt.Errorf("state outputs[%d].destination_id is required", index)
+	}
+	if raw.SourceID == nil || *raw.SourceID == "" {
+		return SharedRootOutputFile{}, fmt.Errorf("state outputs[%d].source_id is required", index)
+	}
+	if raw.SourceDigest == nil || *raw.SourceDigest == "" {
+		return SharedRootOutputFile{}, fmt.Errorf("state outputs[%d].source_digest is required", index)
+	}
+	sourceCreated, err := parseRequiredTime(fmt.Sprintf("state outputs[%d].source_created", index), raw.SourceCreated)
+	if err != nil {
+		return SharedRootOutputFile{}, err
+	}
+	createdAt, err := parseRequiredTime(fmt.Sprintf("state outputs[%d].created_at", index), raw.CreatedAt)
+	if err != nil {
+		return SharedRootOutputFile{}, err
+	}
+	updatedAt, err := parseRequiredTime(fmt.Sprintf("state outputs[%d].updated_at", index), raw.UpdatedAt)
+	if err != nil {
+		return SharedRootOutputFile{}, err
+	}
+	return SharedRootOutputFile{
+		Path:       *raw.Path,
+		Kind:       *raw.Kind,
+		SourcePath: *raw.SourcePath,
+		Transform:  raw.Transform,
+		URL:        raw.URL,
+		SHA256:     *raw.SHA256,
+		Size:       *raw.Size,
+		Owner: OwnerScope{
+			PipelineID:    *raw.PipelineID,
+			DestinationID: *raw.DestinationID,
+		},
+		SourceID:      *raw.SourceID,
+		SourceDigest:  *raw.SourceDigest,
+		SourceCreated: sourceCreated,
+		CreatedAt:     createdAt,
+		UpdatedAt:     updatedAt,
+	}, nil
+}
+
+func (s SharedRootState) CreatedAtString() string {
+	return s.CreatedAt.UTC().Format(time.RFC3339)
+}
+
+func (s SharedRootState) UpdatedAtString() string {
+	return s.UpdatedAt.UTC().Format(time.RFC3339)
+}
+
+func (o SharedRootOutputFile) SourceCreatedString() string {
+	return o.SourceCreated.UTC().Format(time.RFC3339)
+}
+
+func (o SharedRootOutputFile) CreatedAtString() string {
+	return o.CreatedAt.UTC().Format(time.RFC3339)
+}
+
+func (o SharedRootOutputFile) UpdatedAtString() string {
+	return o.UpdatedAt.UTC().Format(time.RFC3339)
+}
+
+func (s SharedRootState) MarshalJSON() ([]byte, error) {
+	type stateJSON struct {
+		SchemaVersion      int                    `json:"schema_version"`
+		DistributorVersion string                 `json:"distributor_version,omitempty"`
+		CreatedAt          string                 `json:"created_at"`
+		UpdatedAt          string                 `json:"updated_at"`
+		State              StatePolicy            `json:"state"`
+		Owners             []OwnerRecord          `json:"owners"`
+		Outputs            []SharedRootOutputFile `json:"outputs"`
+	}
+	return json.Marshal(stateJSON{
+		SchemaVersion:      s.SchemaVersion,
+		DistributorVersion: s.DistributorVersion,
+		CreatedAt:          s.CreatedAtString(),
+		UpdatedAt:          s.UpdatedAtString(),
+		State:              s.State,
+		Owners:             s.Owners,
+		Outputs:            s.Outputs,
+	})
+}
+
+func (o OwnerRecord) MarshalJSON() ([]byte, error) {
+	type sourceJSON struct {
+		Manifest bundle.Manifest `json:"manifest"`
+	}
+	type ownerJSON struct {
+		PipelineID     string               `json:"pipeline_id"`
+		DestinationID  string               `json:"destination_id"`
+		Reconciliation ReconciliationPolicy `json:"reconciliation"`
+		Source         sourceJSON           `json:"source"`
+		Links          *LinkState           `json:"links,omitempty"`
+	}
+	return json.Marshal(ownerJSON{
+		PipelineID:     o.Scope.PipelineID,
+		DestinationID:  o.Scope.DestinationID,
+		Reconciliation: o.Reconciliation,
+		Source:         sourceJSON{Manifest: o.Source.Manifest},
+		Links:          o.Links,
+	})
+}
+
+func (o SharedRootOutputFile) MarshalJSON() ([]byte, error) {
+	type outputJSON struct {
+		Path          string `json:"path"`
+		Kind          string `json:"kind"`
+		SourcePath    string `json:"source_path"`
+		Transform     string `json:"transform,omitempty"`
+		URL           string `json:"url,omitempty"`
+		SHA256        string `json:"sha256"`
+		Size          int64  `json:"size"`
+		PipelineID    string `json:"pipeline_id"`
+		DestinationID string `json:"destination_id"`
+		SourceID      string `json:"source_id"`
+		SourceDigest  string `json:"source_digest"`
+		SourceCreated string `json:"source_created"`
+		CreatedAt     string `json:"created_at"`
+		UpdatedAt     string `json:"updated_at"`
+	}
+	return json.Marshal(outputJSON{
+		Path:          o.Path,
+		Kind:          o.Kind,
+		SourcePath:    o.SourcePath,
+		Transform:     o.Transform,
+		URL:           o.URL,
+		SHA256:        o.SHA256,
+		Size:          o.Size,
+		PipelineID:    o.Owner.PipelineID,
+		DestinationID: o.Owner.DestinationID,
+		SourceID:      o.SourceID,
+		SourceDigest:  o.SourceDigest,
+		SourceCreated: o.SourceCreatedString(),
+		CreatedAt:     o.CreatedAtString(),
+		UpdatedAt:     o.UpdatedAtString(),
+	})
+}
+
+func ValidateSharedRoot(s SharedRootState) error {
+	if s.SchemaVersion != SharedRootSchemaVersion {
+		return fmt.Errorf("state schema_version must be %d", SharedRootSchemaVersion)
+	}
+	if s.CreatedAt.IsZero() {
+		return fmt.Errorf("state created_at is required")
+	}
+	if s.UpdatedAt.IsZero() {
+		return fmt.Errorf("state updated_at is required")
+	}
+	if s.State.Mode != StateModeSharedRoot {
+		return fmt.Errorf("state state.mode must be %s", StateModeSharedRoot)
+	}
+	if s.Owners == nil {
+		return fmt.Errorf("state owners is required")
+	}
+	owners := make(map[OwnerScope]OwnerRecord, len(s.Owners))
+	for index, owner := range s.Owners {
+		if err := validateOwnerRecord(index, owner); err != nil {
+			return err
+		}
+		if _, exists := owners[owner.Scope]; exists {
+			return fmt.Errorf("state owners[%d] duplicates owner %s/%s", index, owner.Scope.PipelineID, owner.Scope.DestinationID)
+		}
+		owners[owner.Scope] = owner
+	}
+	if s.Outputs == nil {
+		return fmt.Errorf("state outputs is required")
+	}
+	seenPaths := make(map[string]struct{}, len(s.Outputs))
+	for index, output := range s.Outputs {
+		if err := validateSharedRootOutput(index, output, owners); err != nil {
+			return err
+		}
+		if _, exists := seenPaths[output.Path]; exists {
+			return fmt.Errorf("state outputs[%d].path duplicates %q", index, output.Path)
+		}
+		seenPaths[output.Path] = struct{}{}
+	}
+	return nil
+}
+
+func validateOwnerRecord(index int, owner OwnerRecord) error {
+	if owner.Scope.PipelineID == "" {
+		return fmt.Errorf("state owners[%d].pipeline_id is required", index)
+	}
+	if owner.Scope.DestinationID == "" {
+		return fmt.Errorf("state owners[%d].destination_id is required", index)
+	}
+	if owner.Reconciliation.Mode != config.ReconciliationModeReplace && owner.Reconciliation.Mode != config.ReconciliationModeMerge {
+		return fmt.Errorf("state owners[%d].reconciliation.mode must be %s or %s", index, config.ReconciliationModeReplace, config.ReconciliationModeMerge)
+	}
+	if err := validateEmbeddedManifest(owner.Source.Manifest); err != nil {
+		return fmt.Errorf("state owners[%d].source.manifest: %w", index, err)
+	}
+	if owner.Links != nil && owner.Links.PrimaryURL != "" {
+		if err := link.ValidateHTTPURL(owner.Links.PrimaryURL); err != nil {
+			return fmt.Errorf("state owners[%d].links.primary_url: %w", index, err)
+		}
+	}
+	return nil
+}
+
+func validateSharedRootOutput(index int, output SharedRootOutputFile, owners map[OwnerScope]OwnerRecord) error {
+	if err := storage.ValidatePath(output.Path); err != nil {
+		return fmt.Errorf("state outputs[%d].path: %w", index, err)
+	}
+	switch output.Kind {
+	case OutputKindSource, OutputKindGenerated:
+	default:
+		return fmt.Errorf("state outputs[%d].kind must be source or generated", index)
+	}
+	if err := storage.ValidatePath(output.SourcePath); err != nil {
+		return fmt.Errorf("state outputs[%d].source_path: %w", index, err)
+	}
+	if output.Kind == OutputKindGenerated && output.Transform == "" {
+		return fmt.Errorf("state outputs[%d].transform is required for generated output", index)
+	}
+	if output.URL != "" {
+		if err := link.ValidateHTTPURL(output.URL); err != nil {
+			return fmt.Errorf("state outputs[%d].url: %w", index, err)
+		}
+	}
+	if err := bundle.ValidateDigest(output.SHA256); err != nil {
+		return fmt.Errorf("state outputs[%d].sha256: %w", index, err)
+	}
+	if output.Size < 0 {
+		return fmt.Errorf("state outputs[%d].size must be non-negative", index)
+	}
+	if output.Owner.PipelineID == "" {
+		return fmt.Errorf("state outputs[%d].pipeline_id is required", index)
+	}
+	if output.Owner.DestinationID == "" {
+		return fmt.Errorf("state outputs[%d].destination_id is required", index)
+	}
+	if _, exists := owners[output.Owner]; !exists {
+		return fmt.Errorf("state outputs[%d] references unknown owner %s/%s", index, output.Owner.PipelineID, output.Owner.DestinationID)
+	}
+	if output.SourceID == "" {
+		return fmt.Errorf("state outputs[%d].source_id is required", index)
+	}
+	if err := bundle.ValidateDigest(output.SourceDigest); err != nil {
+		return fmt.Errorf("state outputs[%d].source_digest: %w", index, err)
+	}
+	if output.SourceCreated.IsZero() {
+		return fmt.Errorf("state outputs[%d].source_created is required", index)
+	}
+	if output.CreatedAt.IsZero() {
+		return fmt.Errorf("state outputs[%d].created_at is required", index)
+	}
+	if output.UpdatedAt.IsZero() {
+		return fmt.Errorf("state outputs[%d].updated_at is required", index)
+	}
+	return nil
+}

internal/state/shared_root_test.go

@@ -0,0 +1,320 @@
+package state
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
+)
+
+func TestParseDocumentHandlesSingleOwnerAndSharedRoot(t *testing.T) {
+	singleOwner, err := ParseDocument([]byte(validStateJSON(t)))
+	if err != nil {
+		t.Fatalf("ParseDocument(single owner) error = %v", err)
+	}
+	if singleOwner.SingleOwner == nil || singleOwner.SharedRoot != nil {
+		t.Fatalf("single owner document = %#v", singleOwner)
+	}
+
+	sharedRoot, err := ParseDocument([]byte(validSharedRootStateJSON(t)))
+	if err != nil {
+		t.Fatalf("ParseDocument(shared root) error = %v", err)
+	}
+	if sharedRoot.SharedRoot == nil || sharedRoot.SingleOwner != nil {
+		t.Fatalf("shared root document = %#v", sharedRoot)
+	}
+}
+
+func TestParseSharedRootState(t *testing.T) {
+	state, err := ParseSharedRoot([]byte(validSharedRootStateJSON(t)))
+	if err != nil {
+		t.Fatalf("ParseSharedRoot() error = %v", err)
+	}
+	if got, want := state.SchemaVersion, SharedRootSchemaVersion; got != want {
+		t.Fatalf("schema version = %d, want %d", got, want)
+	}
+	if got, want := state.CreatedAtString(), "2026-05-30T11:12:00Z"; got != want {
+		t.Fatalf("created_at = %q, want %q", got, want)
+	}
+	if got, want := state.State.Mode, StateModeSharedRoot; got != want {
+		t.Fatalf("state mode = %q, want %q", got, want)
+	}
+	if got, want := len(state.Owners), 2; got != want {
+		t.Fatalf("owner count = %d, want %d", got, want)
+	}
+	if got, want := len(state.Outputs), 2; got != want {
+		t.Fatalf("output count = %d, want %d", got, want)
+	}
+	scope := CurrentOwnerScope("reports", "archive")
+	manifest, ok := state.SourceManifest(scope)
+	if !ok {
+		t.Fatal("SourceManifest() ok = false, want true")
+	}
+	if got, want := manifest.ID, validManifest(t).ID; got != want {
+		t.Fatalf("source manifest id = %q, want %q", got, want)
+	}
+}
+
+func TestParseSharedRootRejectsInvalidMetadata(t *testing.T) {
+	tests := map[string]func(string) string{
+		"schema": func(body string) string {
+			return strings.Replace(body, `"schema_version": 3`, `"schema_version": 2`, 1)
+		},
+		"state mode": func(body string) string {
+			return strings.Replace(body, `"mode": "shared_root"`, `"mode": "single_owner"`, 1)
+		},
+		"duplicate owner": func(body string) string {
+			return strings.Replace(body, `"destination_id": "html"`, `"destination_id": "archive"`, 1)
+		},
+		"unknown output owner": func(body string) string {
+			return strings.Replace(body, `"destination_id": "html",`, `"destination_id": "missing",`, 1)
+		},
+		"duplicate output": func(body string) string {
+			return strings.Replace(body, `"path": "report.html"`, `"path": "report.md"`, 1)
+		},
+		"invalid source digest": func(body string) string {
+			return strings.Replace(body, `"source_digest": "sha256:`, `"source_digest": "SHA256:`, 1)
+		},
+		"invalid owner link": func(body string) string {
+			return strings.Replace(body, `"primary_url": "https://reports.example.com/archive/report.md"`, `"primary_url": "file:///tmp/report.md"`, 1)
+		},
+	}
+	for name, mutate := range tests {
+		t.Run(name, func(t *testing.T) {
+			_, err := ParseSharedRoot([]byte(mutate(validSharedRootStateJSON(t))))
+			if err == nil {
+				t.Fatal("ParseSharedRoot() error = nil, want error")
+			}
+		})
+	}
+}
+
+func TestSharedRootMarshalNormalizesTimestamps(t *testing.T) {
+	state := validSharedRootState(t)
+	state.CreatedAt = time.Date(2026, 5, 30, 13, 12, 0, 0, time.FixedZone("offset", 2*60*60))
+	state.UpdatedAt = state.CreatedAt
+	state.Outputs[0].SourceCreated = state.CreatedAt
+	state.Outputs[0].CreatedAt = state.CreatedAt
+	state.Outputs[0].UpdatedAt = state.CreatedAt
+
+	data, err := json.Marshal(state)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	for _, want := range []string{
+		`"created_at":"2026-05-30T11:12:00Z"`,
+		`"updated_at":"2026-05-30T11:12:00Z"`,
+		`"source_created":"2026-05-30T11:12:00Z"`,
+	} {
+		if !strings.Contains(string(data), want) {
+			t.Fatalf("json = %s, want %s", data, want)
+		}
+	}
+}
+
+func TestSharedRootOutputHelpers(t *testing.T) {
+	state := validSharedRootState(t)
+	archive := CurrentOwnerScope("reports", "archive")
+	html := CurrentOwnerScope("reports", "html")
+
+	if got, want := state.ManagedOutputPaths(archive), []string{"report.md"}; strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("archive paths = %#v, want %#v", got, want)
+	}
+	if got, want := state.AllManagedOutputPaths(), []string{"report.md", "report.html"}; strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("all paths = %#v, want %#v", got, want)
+	}
+	conflict, ok := state.PathOwnershipConflict(archive, []string{"report.html"})
+	if !ok || conflict.Owner != html {
+		t.Fatalf("conflict = %#v ok=%t, want html owner conflict", conflict, ok)
+	}
+}
+
+func TestRemoveMissingSharedRootOwnerOutputs(t *testing.T) {
+	state := validSharedRootState(t)
+	archive := CurrentOwnerScope("reports", "archive")
+	next, changed := RemoveMissingSharedRootOwnerOutputs(state, archive, []string{"report.md", "report.html"})
+	if !changed {
+		t.Fatal("RemoveMissingSharedRootOwnerOutputs() changed = false, want true")
+	}
+	if got, want := next.AllManagedOutputPaths(), []string{"report.html"}; strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("paths = %#v, want %#v", got, want)
+	}
+	if _, ok := next.OutputOwner("report.html"); !ok {
+		t.Fatal("report.html owner missing, want unrelated owner preserved")
+	}
+}
+
+func TestRemoveMissingSharedRootOutputs(t *testing.T) {
+	state := validSharedRootState(t)
+	next, changed := RemoveMissingSharedRootOutputs(state, []string{"report.md", "report.html"})
+	if !changed {
+		t.Fatal("RemoveMissingSharedRootOutputs() changed = false, want true")
+	}
+	if got := next.AllManagedOutputPaths(); len(got) != 0 {
+		t.Fatalf("paths = %#v, want none", got)
+	}
+}
+
+func TestSharedRootProjectAndMergeOwnerOutputs(t *testing.T) {
+	state := validSharedRootState(t)
+	archive := CurrentOwnerScope("reports", "archive")
+	owner, ok := state.Owner(archive)
+	if !ok {
+		t.Fatal("Owner() ok = false, want true")
+	}
+	now := time.Date(2026, 5, 30, 12, 30, 0, 0, time.UTC)
+	planned := ProjectSharedRootOutputs([]OutputProjection{{
+		Path:       "report.md",
+		Kind:       OutputKindSource,
+		SourcePath: "report.md",
+		SHA256:     validManifest(t).Files[0].SHA256,
+		Size:       validManifest(t).Files[0].Size,
+	}, {
+		Path:       "summary.txt",
+		Kind:       OutputKindSource,
+		SourcePath: "summary.txt",
+		SHA256:     validManifest(t).Files[1].SHA256,
+		Size:       validManifest(t).Files[1].Size,
+	}}, state.Outputs, archive, validManifest(t), now)
+
+	merged, err := MergeOwnerOutputs(state, archive, owner, planned)
+	if err != nil {
+		t.Fatalf("MergeOwnerOutputs() error = %v", err)
+	}
+	if got, want := merged.AllManagedOutputPaths(), []string{"report.md", "report.html", "summary.txt"}; strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("merged paths = %#v, want %#v", got, want)
+	}
+	if merged.Outputs[0].CreatedAt.Equal(now) {
+		t.Fatalf("merged updated output created_at = %s, want preserved timestamp", merged.Outputs[0].CreatedAt)
+	}
+	if !merged.Outputs[0].UpdatedAt.Equal(now) {
+		t.Fatalf("merged updated output updated_at = %s, want %s", merged.Outputs[0].UpdatedAt, now)
+	}
+
+	replaced, err := ReplaceOwnerOutputs(state, archive, owner, planned)
+	if err != nil {
+		t.Fatalf("ReplaceOwnerOutputs() error = %v", err)
+	}
+	if got, want := replaced.AllManagedOutputPaths(), []string{"report.html", "report.md", "summary.txt"}; strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("replaced paths = %#v, want %#v", got, want)
+	}
+}
+
+func TestSharedRootOwnerOutputHelpersRejectConflicts(t *testing.T) {
+	state := validSharedRootState(t)
+	archive := CurrentOwnerScope("reports", "archive")
+	owner, ok := state.Owner(archive)
+	if !ok {
+		t.Fatal("Owner() ok = false, want true")
+	}
+	planned := []SharedRootOutputFile{{
+		Path:      "report.html",
+		Kind:      OutputKindSource,
+		Owner:     archive,
+		CreatedAt: time.Date(2026, 5, 30, 12, 30, 0, 0, time.UTC),
+		UpdatedAt: time.Date(2026, 5, 30, 12, 30, 0, 0, time.UTC),
+	}}
+
+	if _, err := MergeOwnerOutputs(state, archive, owner, planned); err == nil {
+		t.Fatal("MergeOwnerOutputs() error = nil, want owner conflict")
+	}
+	if _, err := ReplaceOwnerOutputs(state, archive, owner, planned); err == nil {
+		t.Fatal("ReplaceOwnerOutputs() error = nil, want owner conflict")
+	}
+}
+
+func TestCompareSharedRootOwnerScopesCurrentOwner(t *testing.T) {
+	state := validSharedRootState(t)
+	source := validManifest(t)
+	source.Created = source.Created.Add(time.Hour)
+	scope := CurrentOwnerScope("reports", "archive")
+
+	comparison := CompareSharedRootOwner(source, scope, DestinationStatus{SharedRoot: &state, HasContents: true})
+	if comparison.Outcome != OutcomeDestinationOlder {
+		t.Fatalf("comparison = %#v, want destination older for current owner", comparison)
+	}
+
+	missing := CompareSharedRootOwner(source, CurrentOwnerScope("missing", "archive"), DestinationStatus{SharedRoot: &state, HasContents: true})
+	if missing.Outcome != OutcomeDestinationAbsent {
+		t.Fatalf("missing owner comparison = %#v, want destination absent", missing)
+	}
+}
+
+func TestCompareSharedRootOwnerAcceptsMatchingSingleOwnerState(t *testing.T) {
+	singleOwner, err := Parse([]byte(validStateJSON(t)))
+	if err != nil {
+		t.Fatalf("Parse() error = %v", err)
+	}
+	source := singleOwner.Source.Manifest
+	source.Created = source.Created.Add(time.Hour)
+	scope := CurrentOwnerScope(singleOwner.PipelineID, singleOwner.DestinationID)
+
+	comparison := CompareSharedRootOwner(source, scope, DestinationStatus{State: &singleOwner, HasContents: true})
+	if comparison.Outcome != OutcomeDestinationOlder {
+		t.Fatalf("comparison = %#v, want destination older", comparison)
+	}
+}
+
+func validSharedRootStateJSON(t *testing.T) string {
+	t.Helper()
+	data, err := json.MarshalIndent(validSharedRootState(t), "", "  ")
+	if err != nil {
+		t.Fatalf("marshal shared root state: %v", err)
+	}
+	return string(data)
+}
+
+func validSharedRootState(t *testing.T) SharedRootState {
+	t.Helper()
+	source := validManifest(t)
+	htmlSource := source
+	htmlSource.Files = append([]bundle.ManifestFile(nil), source.Files...)
+	createdAt := time.Date(2026, 5, 30, 11, 12, 0, 0, time.UTC)
+	return SharedRootState{
+		SchemaVersion:      SharedRootSchemaVersion,
+		DistributorVersion: "dev",
+		CreatedAt:          createdAt,
+		UpdatedAt:          createdAt,
+		State:              StatePolicy{Mode: StateModeSharedRoot},
+		Owners: []OwnerRecord{{
+			Scope:          CurrentOwnerScope("reports", "archive"),
+			Reconciliation: ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
+			Source:         SourceState{Manifest: source},
+			Links:          &LinkState{PrimaryURL: "https://reports.example.com/archive/report.md"},
+		}, {
+			Scope:          CurrentOwnerScope("reports", "html"),
+			Reconciliation: ReconciliationPolicy{Mode: config.ReconciliationModeMerge},
+			Source:         SourceState{Manifest: htmlSource},
+		}},
+		Outputs: []SharedRootOutputFile{{
+			Path:          "report.md",
+			Kind:          OutputKindSource,
+			SourcePath:    "report.md",
+			SHA256:        source.Files[0].SHA256,
+			Size:          source.Files[0].Size,
+			Owner:         CurrentOwnerScope("reports", "archive"),
+			SourceID:      source.ID,
+			SourceDigest:  source.Digest,
+			SourceCreated: source.Created,
+			CreatedAt:     createdAt,
+			UpdatedAt:     createdAt,
+		}, {
+			Path:          "report.html",
+			Kind:          OutputKindGenerated,
+			SourcePath:    "report.md",
+			Transform:     "markdown_to_html",
+			URL:           "https://reports.example.com/html/report.html",
+			SHA256:        "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+			Size:          128,
+			Owner:         CurrentOwnerScope("reports", "html"),
+			SourceID:      htmlSource.ID,
+			SourceDigest:  htmlSource.Digest,
+			SourceCreated: htmlSource.Created,
+			CreatedAt:     createdAt,
+			UpdatedAt:     createdAt,
+		}},
+	}
+}

internal/state/validate.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 
 	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
 	"gitea.maximumdirect.net/eric/distributor/internal/link"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 )
@@ -26,6 +27,18 @@ func Validate(s DistributorState) error {
 	if s.PublishedAt.IsZero() {
 		return fmt.Errorf("state published_at is required")
 	}
+	if s.CreatedAt.IsZero() {
+		return fmt.Errorf("state created_at is required")
+	}
+	if s.UpdatedAt.IsZero() {
+		return fmt.Errorf("state updated_at is required")
+	}
+	if s.State.Mode != StateModeSingleOwner {
+		return fmt.Errorf("state state.mode must be %s", StateModeSingleOwner)
+	}
+	if s.Reconciliation.Mode != config.ReconciliationModeReplace && s.Reconciliation.Mode != config.ReconciliationModeMerge {
+		return fmt.Errorf("state reconciliation.mode must be %s or %s", config.ReconciliationModeReplace, config.ReconciliationModeMerge)
+	}
 	if err := validateEmbeddedManifest(s.Source.Manifest); err != nil {
 		return fmt.Errorf("state source.manifest: %w", err)
 	}
@@ -80,5 +93,11 @@ func validateOutput(index int, output OutputFile) error {
 	if output.Size < 0 {
 		return fmt.Errorf("state outputs[%d].size must be non-negative", index)
 	}
+	if output.CreatedAt.IsZero() {
+		return fmt.Errorf("state outputs[%d].created_at is required", index)
+	}
+	if output.UpdatedAt.IsZero() {
+		return fmt.Errorf("state outputs[%d].updated_at is required", index)
+	}
 	return nil
 }

internal/storage/backend.go

@@ -29,6 +29,7 @@ type Backend interface {
 	Stat(ctx context.Context, path string) (Entry, error)
 	Walk(ctx context.Context, prefix string, opts WalkOptions, fn WalkFunc) error
 	HasAny(ctx context.Context, prefix string) (bool, error)
+	DeleteManagedOutputs(ctx context.Context, bundlePath string, managedOutputPaths []string, opts DeleteOptions) error
 	DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts DeleteOptions) error
 	DeletePrefix(ctx context.Context, prefix string, opts DeleteOptions) error
 }

internal/storage/errors.go

@@ -20,18 +20,19 @@ const (
 )
 
 const (
-	OpValidatePath        = "validate path"
+	OpValidatePath         = "validate path"
-	OpReadFile            = "read file"
+	OpReadFile             = "read file"
-	OpOpenReader          = "open reader"
+	OpOpenReader           = "open reader"
-	OpWriteFile           = "write file"
+	OpWriteFile            = "write file"
-	OpWriteFrom           = "write stream"
+	OpWriteFrom            = "write stream"
-	OpStat                = "stat"
+	OpStat                 = "stat"
-	OpWalk                = "walk"
+	OpWalk                 = "walk"
-	OpHasAny              = "has any"
+	OpHasAny               = "has any"
-	OpDeleteManagedBundle = "delete managed bundle"
+	OpDeleteManagedOutputs = "delete managed outputs"
-	OpDeletePrefix        = "delete prefix"
+	OpDeleteManagedBundle  = "delete managed bundle"
-	OpRegisterBackend     = "register backend"
+	OpDeletePrefix         = "delete prefix"
-	OpOpenBackend         = "open backend"
+	OpRegisterBackend      = "register backend"
+	OpOpenBackend          = "open backend"
 )
 
 type Error struct {

internal/storage/fake/backend.go

@@ -159,23 +159,35 @@ func (b *Backend) HasAny(ctx context.Context, prefix string) (bool, error) {
 }
 
 func (b *Backend) DeleteManagedBundle(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	return b.deleteManagedTargets(ctx, storage.OpDeleteManagedBundle, func() ([]string, error) {
+		return storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	}, opts)
+}
+
+func (b *Backend) DeleteManagedOutputs(ctx context.Context, bundlePath string, managedOutputPaths []string, opts storage.DeleteOptions) error {
+	return b.deleteManagedTargets(ctx, storage.OpDeleteManagedOutputs, func() ([]string, error) {
+		return storage.ManagedOutputTargets(bundlePath, managedOutputPaths)
+	}, opts)
+}
+
+func (b *Backend) deleteManagedTargets(ctx context.Context, op string, targetsFunc func() ([]string, error), opts storage.DeleteOptions) error {
 	if err := ctx.Err(); err != nil {
 		return err
 	}
-	targets, err := storage.ManagedBundleTargets(bundlePath, managedOutputPaths)
+	targets, err := targetsFunc()
 	if err != nil {
 		return err
 	}
 
 	for _, target := range targets {
 		if _, ok := b.dirs[target]; ok {
-			return storage.NewError(storage.OpDeleteManagedBundle, backendName, target, storage.ErrUnsupported, nil)
+			return storage.NewError(op, backendName, target, storage.ErrUnsupported, nil)
 		}
 		if !b.exists(target) {
 			if opts.IgnoreMissing {
 				continue
 			}
-			return storage.NewError(storage.OpDeleteManagedBundle, backendName, target, storage.ErrNotFound, nil)
+			return storage.NewError(op, backendName, target, storage.ErrNotFound, nil)
 		}
 		delete(b.files, target)
 		delete(b.symlinks, target)

internal/storage/path.go

@@ -50,10 +50,23 @@ func DisplayPath(path string) string {
 }
 
 func ManagedBundleTargets(bundlePath string, managedOutputPaths []string) ([]string, error) {
+	targets, err := ManagedOutputTargets(bundlePath, managedOutputPaths)
+	if err != nil {
+		return nil, err
+	}
+	statePath, err := StatePath(bundlePath)
+	if err != nil {
+		return nil, err
+	}
+	targets = append(targets, statePath)
+	return targets, nil
+}
+
+func ManagedOutputTargets(bundlePath string, managedOutputPaths []string) ([]string, error) {
 	if err := ValidatePrefix(bundlePath); err != nil {
 		return nil, err
 	}
-	targets := make([]string, 0, len(managedOutputPaths)+1)
+	targets := make([]string, 0, len(managedOutputPaths))
 	for _, outputPath := range managedOutputPaths {
 		target, err := Join(bundlePath, outputPath)
 		if err != nil {
@@ -61,11 +74,6 @@ func ManagedBundleTargets(bundlePath string, managedOutputPaths []string) ([]str
 		}
 		targets = append(targets, target)
 	}
-	statePath, err := StatePath(bundlePath)
-	if err != nil {
-		return nil, err
-	}
-	targets = append(targets, statePath)
 	return targets, nil
 }
 

internal/storage/path_test.go

@@ -132,6 +132,22 @@ func TestManagedBundleTargetsRejectsInvalidOutputPath(t *testing.T) {
 	}
 }
 
+func TestManagedOutputTargetsOmitsStateFile(t *testing.T) {
+	targets, err := ManagedOutputTargets("bundle", []string{"report.md", "nested/report.html"})
+	if err != nil {
+		t.Fatalf("ManagedOutputTargets() error = %v", err)
+	}
+	want := []string{"bundle/report.md", "bundle/nested/report.html"}
+	if len(targets) != len(want) {
+		t.Fatalf("targets = %v, want %v", targets, want)
+	}
+	for index := range want {
+		if targets[index] != want[index] {
+			t.Fatalf("targets = %v, want %v", targets, want)
+		}
+	}
+}
+
 func TestListSortsEntries(t *testing.T) {
 	backend := walkBackend{
 		entries: []Entry{
@@ -215,6 +231,10 @@ func (b walkBackend) DeleteManagedBundle(context.Context, string, []string, Dele
 	return nil
 }
 
+func (b walkBackend) DeleteManagedOutputs(context.Context, string, []string, DeleteOptions) error {
+	return nil
+}
+
 func (b walkBackend) DeletePrefix(context.Context, string, DeleteOptions) error {
 	return nil
 }

internal/testutil/fixtures.go

@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"gitea.maximumdirect.net/eric/distributor/internal/bundle"
+	"gitea.maximumdirect.net/eric/distributor/internal/config"
 	"gitea.maximumdirect.net/eric/distributor/internal/state"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage"
 	"gitea.maximumdirect.net/eric/distributor/internal/storage/fake"
@@ -329,14 +330,19 @@ func WriteDestinationState(t testing.TB, root, relative string, manifest bundle.
 }
 
 func DestinationState(manifest bundle.Manifest, opts DestinationStateOptions) state.DistributorState {
+	publishedAt := defaultPublishedAt(opts.PublishedAt)
 	return state.DistributorState{
 		SchemaVersion:      state.SchemaVersion,
 		DistributorVersion: opts.DistributorVersion,
 		PipelineID:         defaultString(opts.PipelineID, "reports"),
 		DestinationID:      defaultString(opts.DestinationID, "archive"),
-		PublishedAt:        defaultPublishedAt(opts.PublishedAt),
+		PublishedAt:        publishedAt,
+		CreatedAt:          publishedAt,
+		UpdatedAt:          publishedAt,
+		State:              state.StatePolicy{Mode: state.StateModeSingleOwner},
+		Reconciliation:     state.ReconciliationPolicy{Mode: config.ReconciliationModeReplace},
 		Source:             state.SourceState{Manifest: manifest},
-		Outputs:            sourceOutputs(manifest),
+		Outputs:            sourceOutputs(manifest, publishedAt),
 	}
 }
 
@@ -386,7 +392,7 @@ func sourceFiles(opts BundleOptions) []SourceFile {
 	return files
 }
 
-func sourceOutputs(manifest bundle.Manifest) []state.OutputFile {
+func sourceOutputs(manifest bundle.Manifest, publishedAt time.Time) []state.OutputFile {
 	outputs := make([]state.OutputFile, 0, len(manifest.Files))
 	for _, file := range manifest.Files {
 		outputs = append(outputs, state.OutputFile{
@@ -395,6 +401,8 @@ func sourceOutputs(manifest bundle.Manifest) []state.OutputFile {
 			SourcePath: file.Path,
 			SHA256:     file.SHA256,
 			Size:       file.Size,
+			CreatedAt:  publishedAt,
+			UpdatedAt:  publishedAt,
 		})
 	}
 	return outputs