feat(data): add bounded tenant provenance portability

CHANGELOG.md

@@ -1,4 +1,11 @@
 ## [Unreleased]
+- Proposed: export and restore the project evidence cited in one verified
+  workspace, preserving source links and stable identities. This first slice
+  excludes full mailbox, binary documents, credentials, provider and connector
+  state, embeddings, and audit history. Archives remain bounded to 64 MiB
+  compressed and total uncompressed content, 64 entries, 32 MiB per entry, and
+  a 100:1 compression ratio; invalid archives are rejected before changes.
+  Full customer-exit portability and deployment verification remain open.
 - Proposed: accept manual PDF uploads up to 64MiB after the required processing
   service release is verified and pinned. Larger files are rejected before
   storage or processing with HTTP 413; split the file and upload it again.

backend/alembic/versions/0018_provenance_identity_mappings.py

@@ -0,0 +1,59 @@
+"""Add scoped portable-to-database provenance identity mappings."""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0018_provenance_identity"
+down_revision = "0017_merge_newsdom_carddav_heads"
+branch_labels = None
+depends_on = None
+_MAPPING_TABLE = "provenance_identity_mappings"
+
+
+def upgrade() -> None:
+    inspector = sa.inspect(op.get_bind())
+    if not inspector.has_table(_MAPPING_TABLE):
+        op.create_table(
+            _MAPPING_TABLE,
+            sa.Column("provenance_identity_id", sa.Integer(), primary_key=True),
+            sa.Column("target_user_id", sa.String(), nullable=False),
+            sa.Column("target_organization_id", sa.String(), nullable=False),
+            sa.Column("target_workspace_id", sa.String(), nullable=False),
+            sa.Column("source_user_uid", sa.String(length=64), nullable=False),
+            sa.Column("source_organization_uid", sa.String(), nullable=False),
+            sa.Column("source_workspace_uid", sa.String(), nullable=False),
+            sa.Column("entity_kind", sa.String(length=64), nullable=False),
+            sa.Column("portable_uid", sa.String(length=256), nullable=False),
+            sa.Column("target_database_uid", sa.String(length=96), nullable=False),
+            sa.UniqueConstraint(
+                "target_user_id",
+                "target_organization_id",
+                "target_workspace_id",
+                "source_user_uid",
+                "source_organization_uid",
+                "source_workspace_uid",
+                "entity_kind",
+                "portable_uid",
+                name="uq_provenance_identity_source_target",
+            ),
+            sa.UniqueConstraint(
+                "entity_kind",
+                "target_database_uid",
+                name="uq_provenance_identity_target_uid",
+            ),
+        )
+    op.create_index(
+        "ix_provenance_identity_target_scope",
+        _MAPPING_TABLE,
+        ["target_user_id", "target_organization_id", "target_workspace_id"],
+        if_not_exists=True,
+    )
+
+
+def downgrade() -> None:
+    """Preserve imported identity mappings when application code is rolled back."""
+    # The table may predate this revision via 0001's live metadata bootstrap.
+    # Its portable identity history is not rebuildable from remapped records.
+    # Destructive retirement requires a separate, explicitly governed operation.
+    return None

backend/alembic/versions/0021_merge_provenance_workspace.py

@@ -0,0 +1,16 @@
+"""Join provenance identity and workspace repair histories without rewriting either."""
+
+revision = "0021_merge_provenance_workspace"
+down_revision = ("0018_provenance_identity", "0020_search_trigram_storage")
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Require both existing branches before recording the unified head."""
+    return None
+
+
+def downgrade() -> None:
+    """Reopen the two revision heads without changing customer records."""
+    return None

backend/api/data.py

@@ -7,7 +7,7 @@
 import re
 from typing import Literal, NamedTuple
 
-from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, Response, UploadFile
 from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy import and_, case, func, or_, select
 from sqlalchemy.engine import Row
@@ -35,6 +35,13 @@
     PDF_DOM_RECOGNITION_PENDING_STATUS,
 )
 from services.ontology_service import ontology_service
+from services.tenant_provenance_bundle import (
+    ARCHIVE_MAX_BYTES,
+    ProvenanceArchiveError,
+    TenantProvenanceScope,
+    export_tenant_provenance,
+    import_tenant_provenance,
+)
 from services.webdav_service import webdav_service
 from services.workspace_scope import get_or_create_workspace
 
@@ -46,6 +53,7 @@
 # transport ceiling so large customer PDFs are not accepted by one path and
 # rejected by the next.
 _MAX_PDF_DOM_UPLOAD_BYTES = 64 * 1024 * 1024
+_PROVENANCE_ARCHIVE_MAX_BYTES = ARCHIVE_MAX_BYTES
 ATTACHMENT_PARSE_BREAKDOWN_EVIDENCE_SOURCE = (
     "email_attachments.content_type, "
     "email_attachments.parse_content_type, "
@@ -3192,6 +3200,86 @@ def _quality_checks(
     ]
 
 
+def _provenance_scope(auth_context: AuthContext) -> TenantProvenanceScope:
+    return TenantProvenanceScope(
+        user_id=auth_context.user_id,
+        organization_id=auth_context.organization_id,
+        workspace_id=auth_context.workspace_id,
+    )
+
+
+def _require_authoritative_provenance_scope(auth_context: AuthContext) -> None:
+    if auth_context.session_verifier != "oidc":
+        raise HTTPException(
+            status_code=403,
+            detail="Authoritative workspace membership is required for provenance bundles",
+        )
+
+
+async def _read_provenance_archive(request: Request) -> bytes:
+    content_length = request.headers.get("content-length")
+    if content_length is not None:
+        if not content_length.isdigit():
+            raise HTTPException(status_code=400, detail="Invalid Content-Length")
+        try:
+            declared_bytes = int(content_length)
+        except ValueError as exc:
+            raise HTTPException(
+                status_code=400, detail="Invalid Content-Length"
+            ) from exc
+        if declared_bytes > _PROVENANCE_ARCHIVE_MAX_BYTES:
+            raise HTTPException(status_code=413, detail="Provenance archive too large")
+    archive = bytearray()
+    async for chunk in request.stream():
+        if len(chunk) > _PROVENANCE_ARCHIVE_MAX_BYTES - len(archive):
+            raise HTTPException(status_code=413, detail="Provenance archive too large")
+        archive.extend(chunk)
+    return bytes(archive)
+
+
+@router.get("/provenance-bundle")
+async def download_provenance_bundle(
+    auth_context: AuthContext = Depends(get_auth_context),
+    db: AsyncSession = Depends(get_db),
+) -> Response:
+    _require_authoritative_provenance_scope(auth_context)
+    try:
+        archive = await export_tenant_provenance(db, _provenance_scope(auth_context))
+    except ProvenanceArchiveError as exc:
+        raise HTTPException(
+            status_code=400, detail="Invalid provenance archive"
+        ) from exc
+    return Response(
+        content=archive,
+        media_type="application/zip",
+        headers={"Content-Disposition": 'attachment; filename="naruon-provenance.zip"'},
+    )
+
+
+@router.post("/provenance-bundle/import")
+async def upload_provenance_bundle(
+    request: Request,
+    auth_context: AuthContext = Depends(get_auth_context),
+    db: AsyncSession = Depends(get_db),
+) -> dict[str, object]:
+    _require_authoritative_provenance_scope(auth_context)
+    archive = await _read_provenance_archive(request)
+    try:
+        receipt = await import_tenant_provenance(
+            db, _provenance_scope(auth_context), archive
+        )
+    except ProvenanceArchiveError as exc:
+        raise HTTPException(
+            status_code=400, detail="Invalid provenance archive"
+        ) from exc
+    return {
+        "bundle_uid": receipt.bundle_uid,
+        "manifest_digest": receipt.manifest_digest,
+        "created": receipt.created,
+        "skipped": receipt.skipped,
+    }
+
+
 @router.post("/documents", response_model=DataDocumentActionResponse)
 async def upload_data_document(
     request: DataDocumentUploadRequest,

backend/db/models.py

@@ -1293,6 +1293,45 @@ class ProjectGraphCorrectionRecord(Base):
     )
 
 
+class ProvenanceIdentityMapping(Base):
+    __tablename__ = "provenance_identity_mappings"
+    __table_args__ = (
+        UniqueConstraint(
+            "target_user_id",
+            "target_organization_id",
+            "target_workspace_id",
+            "source_user_uid",
+            "source_organization_uid",
+            "source_workspace_uid",
+            "entity_kind",
+            "portable_uid",
+            name="uq_provenance_identity_source_target",
+        ),
+        UniqueConstraint(
+            "entity_kind",
+            "target_database_uid",
+            name="uq_provenance_identity_target_uid",
+        ),
+        Index(
+            "ix_provenance_identity_target_scope",
+            "target_user_id",
+            "target_organization_id",
+            "target_workspace_id",
+        ),
+    )
+
+    provenance_identity_id: Mapped[int] = mapped_column(primary_key=True)
+    target_user_id: Mapped[str] = mapped_column(String, nullable=False)
+    target_organization_id: Mapped[str] = mapped_column(String, nullable=False)
+    target_workspace_id: Mapped[str] = mapped_column(String, nullable=False)
+    source_user_uid: Mapped[str] = mapped_column(String(64), nullable=False)
+    source_organization_uid: Mapped[str] = mapped_column(String, nullable=False)
+    source_workspace_uid: Mapped[str] = mapped_column(String, nullable=False)
+    entity_kind: Mapped[str] = mapped_column(String(64), nullable=False)
+    portable_uid: Mapped[str] = mapped_column(String(256), nullable=False)
+    target_database_uid: Mapped[str] = mapped_column(String(96), nullable=False)
+
+
 class TenantConfig(Base):
     __tablename__ = "tenant_configs"