Document shared-root publishing

docs/integrations/destination-state.md

@@ -93,7 +93,7 @@ For replacement updates, newly planned outputs are written into state. For merge
 
 Destination reconciliation applies when destination state is older than the source and transfer policy permits replacement.
 
-- `replace`: 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.
+- `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.
@@ -106,6 +106,7 @@ If a merge publication fails after writing outputs, cleanup removes only newly c
 
 - 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.
@@ -113,7 +114,7 @@ If a merge publication fails after writing outputs, cleanup removes only newly c
 - 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`. Merge publication retains omitted managed outputs. 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.
 
 ## Compatibility
 
@@ -194,6 +195,33 @@ Shared-root optional fields:
 
 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
 
 Destination state is internal managed state written by `distributor`. Operators may inspect it during recovery, but normal workflows should not edit it by hand. Source `manifest.json` is not copied as destination state.