feat(clone): v2 full fidelity — share replication + lookup version history

Make the cloned cloud entities match the source, including user-group sharing.

Sharing (sharing.py): extract the user/group axis mapping into reusable helpers
and add replicate_share(), generic over the write mechanism (POST /share/ or a
detail PATCH). Existing /share/-POST phases are unchanged (thin wrapper).
- lookups + agentic projects now replicate shared_to_org + shared_users
  (mapped by email) via their detail PATCH; lookups have no group axis, agentic
  group sharing is polymorphic/read-only and is warned, not dropped silently.

Lookups published-version replay: reproduce each source published version
(stage template + remapped adapters + that version's reference files onto the
draft, then publish in version_number order, recording a lookup_version remap),
then restore the draft to the source's current draft. Assignments now resolve
published-pinned versions via the version remap instead of being skipped.
Residual: assignment_values_snapshot is backend-derived at publish time (best
effort). Fixes list_lookup_versions to unwrap the {"versions": [...]} envelope.

Manual review: auto_approved_users remapped by email (was carried verbatim);
auto_approved_document_classes carried with a verify-on-target warning. MR rows
have no share fields (inherit workflow/org visibility).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CsGrHbs5SWmQkKqiimg6CF

Author: chandrasekharan-zipstack

src/unstract/clone/client.py

@@ -666,6 +666,72 @@ def create_lookup_assignment(self, payload: dict[str, Any]) -> dict[str, Any]:
         """
         return self._request("POST", "lookups/assignments/", json=payload)
 
+    def update_lookup_share(
+        self, lookup_id: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Replicate share state onto a lookup via its detail PATCH.
+
+        ``payload`` carries ``shared_to_org`` + ``shared_users`` (target user
+        pks). The model has no group sharing, so no ``shared_groups`` axis.
+        """
+        return self._request(
+            "PATCH", f"lookups/definitions/{lookup_id}/", json=payload
+        )
+
+    def list_lookup_versions(self, lookup_id: str) -> list[dict[str, Any]]:
+        """List a lookup's versions (draft + published).
+
+        Rows carry ``version_id``, ``is_draft``, ``version_number``,
+        ``version_name``; the detail (``get_lookup_version``) inlines content.
+        """
+        result = self._request(
+            "GET", f"lookups/definitions/{lookup_id}/versions/"
+        )
+        if isinstance(result, list):
+            return result
+        # This endpoint wraps rows as {"versions": [...], "next_version_number"}.
+        return (result or {}).get("versions", (result or {}).get("results", []))
+
+    def get_lookup_version(
+        self, lookup_id: str, version_id: str
+    ) -> dict[str, Any]:
+        """Fetch a version's detail (``prompt_template``, adapters, files)."""
+        return self._request(
+            "GET", f"lookups/definitions/{lookup_id}/versions/{version_id}/"
+        )
+
+    def download_lookup_version_file(
+        self, lookup_id: str, version_id: str, file_id: str
+    ) -> bytes:
+        """Download a published version's reference-file bytes (raw body)."""
+        path = (
+            f"lookups/definitions/{lookup_id}/versions/{version_id}/"
+            f"files/{file_id}/content/"
+        )
+        url = self._url(path)
+        logger.debug("GET %s", url)
+        resp = self._session.get(url, timeout=self.timeout, verify=self.verify)
+        if not 200 <= resp.status_code < 300:
+            raise PlatformAPIError(
+                f"GET {path} returned {resp.status_code}",
+                status_code=resp.status_code,
+                body=resp.text[:2000],
+            )
+        return resp.content
+
+    def publish_lookup_version(
+        self, lookup_id: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Freeze the current draft into a published version.
+
+        ``payload`` carries ``version_name`` (+ optional ``rebind_assignments``).
+        Returns the new published version (``version_id``). Used to replay a
+        source lookup's published-version history onto the target.
+        """
+        return self._request(
+            "POST", f"lookups/definitions/{lookup_id}/versions/", json=payload
+        )
+
     # ----- manual review / HITL (cloud-only) -----
     #
     # Each workflow can hold one RuleEngine row per ``rule_type`` (DB / API)
@@ -779,6 +845,19 @@ def create_agentic_project(self, payload: dict[str, Any]) -> dict[str, Any]:
         """Create an agentic project. Returns the created row (carries ``id``)."""
         return self._request("POST", "agentic/projects/", json=payload)
 
+    def update_agentic_project_share(
+        self, project_id: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Replicate share state onto an agentic project via its detail PATCH.
+
+        ``payload`` carries ``shared_to_org`` + ``shared_users`` (target user
+        pks). ``shared_groups`` is polymorphic/read-only on this serializer and
+        is handled by the share helper's group-omission warning.
+        """
+        return self._request(
+            "PATCH", f"agentic/projects/{project_id}/", json=payload
+        )
+
     def list_agentic_prompt_versions(
         self, *, project_id: str | None = None
     ) -> list[dict[str, Any]]:

src/unstract/clone/phases/agentic_studio.py

@@ -44,6 +44,7 @@
 from unstract.clone.exceptions import NameConflictError
 from unstract.clone.phases.base import Phase, build_post_payload
 from unstract.clone.report import CloneReport, PhaseResult
+from unstract.clone.sharing import replicate_share
 
 logger = logging.getLogger(__name__)
 
@@ -166,9 +167,10 @@ def _clone_project(
                 tgt_project_id,
             )
 
-        # Children + registry write to the real target only.
+        # Children + registry + share write to the real target only.
         if self.ctx.options.dry_run:
             return
+        self._replicate_share(src, name, tgt_project_id, result, lock)
         self._clone_prompt_versions(name, src_project_id, tgt_project_id, result, lock)
         self._clone_schemas(name, src_project_id, tgt_project_id, result, lock)
         self._republish_registry(name, src_project_id, tgt_project_id, result, lock)
@@ -207,6 +209,35 @@ def _build_project_payload(
             payload[slot] = tgt_adapter_id
         return payload
 
+    # ----- share state -----
+
+    def _replicate_share(
+        self,
+        src: dict[str, Any],
+        name: str,
+        tgt_project_id: str,
+        result: PhaseResult,
+        lock: threading.Lock,
+    ) -> None:
+        # The project list/detail share the same serializer, so the source row
+        # already carries shared_users (target-mappable user pks), shared_to_org
+        # and created_by — no detail fetch needed.
+        # ponytail: agentic group sharing is deferred — shared_groups is
+        # polymorphic/read-only on the project serializer (share via the detail
+        # PATCH only reaches shared_users + shared_to_org), so include_groups is
+        # off and a source group share yields a single warning.
+        replicate_share(
+            self.ctx,
+            apply_fn=lambda p: self.ctx.target.update_agentic_project_share(
+                tgt_project_id, p
+            ),
+            entity_label=f"agentic project '{name}'",
+            src=src,
+            result=result,
+            lock=lock,
+            include_groups=False,
+        )
+
     # ----- prompt versions -----
 
     def _clone_prompt_versions(