-- Source tracking for material property datasets and analyses.
-- Polymorphic provenance: source_type + source_id (no per-type FKs).
-- source_id has no DB FK — it is a provenance breadcrumb, and integrity is
-- enforced in the service layer via RLS-scoped existence checks.

-- material_property_datasets
ALTER TABLE "public"."material_property_datasets"
    ADD COLUMN IF NOT EXISTS "source_type" "text",
    ADD COLUMN IF NOT EXISTS "source_id" "uuid",
    ADD COLUMN IF NOT EXISTS "source_label" "text";

DO $$ BEGIN
    ALTER TABLE "public"."material_property_datasets"
        ADD CONSTRAINT "material_property_datasets_source_type_check"
        CHECK ("source_type" IN ('pipeline','simple_pipeline','analysis','manual')
               OR "source_type" IS NULL);
EXCEPTION WHEN duplicate_object THEN NULL;
END $$;

DO $$ BEGIN
    ALTER TABLE "public"."material_property_datasets"
        ADD CONSTRAINT "material_property_datasets_source_consistency_check"
        CHECK (
            ("source_type" IN ('pipeline','simple_pipeline','analysis') AND "source_id" IS NOT NULL)
            OR ("source_type" = 'manual' AND "source_id" IS NULL)
            OR ("source_type" IS NULL AND "source_id" IS NULL)
        );
EXCEPTION WHEN duplicate_object THEN NULL;
END $$;

-- analyses
ALTER TABLE "public"."analyses"
    ADD COLUMN IF NOT EXISTS "source_type" "text",
    ADD COLUMN IF NOT EXISTS "source_id" "uuid",
    ADD COLUMN IF NOT EXISTS "source_label" "text";

DO $$ BEGIN
    ALTER TABLE "public"."analyses"
        ADD CONSTRAINT "analyses_source_type_check"
        CHECK ("source_type" IN ('pipeline','simple_pipeline','analysis','manual')
               OR "source_type" IS NULL);
EXCEPTION WHEN duplicate_object THEN NULL;
END $$;

DO $$ BEGIN
    ALTER TABLE "public"."analyses"
        ADD CONSTRAINT "analyses_source_consistency_check"
        CHECK (
            ("source_type" IN ('pipeline','simple_pipeline','analysis') AND "source_id" IS NOT NULL)
            OR ("source_type" = 'manual' AND "source_id" IS NULL)
            OR ("source_type" IS NULL AND "source_id" IS NULL)
        );
EXCEPTION WHEN duplicate_object THEN NULL;
END $$;

COMMENT ON COLUMN "public"."material_property_datasets"."source_type" IS
    'Provenance kind: pipeline | simple_pipeline | analysis | manual (or NULL if unknown).';
COMMENT ON COLUMN "public"."material_property_datasets"."source_id" IS
    'ID of the source row (no DB FK; polymorphic). NULL for manual/unknown.';
COMMENT ON COLUMN "public"."analyses"."source_type" IS
    'Provenance kind: pipeline | simple_pipeline | analysis | manual (or NULL if unknown).';
COMMENT ON COLUMN "public"."analyses"."source_id" IS
    'ID of the source row (no DB FK; polymorphic). NULL for manual/unknown.';

git add supabase/migrations/20260718000000_add_source_tracking.sql
git commit -m "feat(db): add source tracking columns to material_property_datasets and analyses"

# backend/tests/test_sources.py
import pytest
from pydantic import BaseModel, ValidationError

from src.pydantic_models.sources import SourceType, validate_source_consistency


class _Model(BaseModel):
    source_type: SourceType | None = None
    source_id: str | None = None
    source_label: str | None = None

    _check = validate_source_consistency()


def test_all_none_ok():
    m = _Model()
    assert m.source_type is None and m.source_id is None


def test_manual_without_id_ok():
    m = _Model(source_type=SourceType.MANUAL)
    assert m.source_type == SourceType.MANUAL


def test_manual_with_id_rejected():
    with pytest.raises(ValidationError):
        _Model(source_type=SourceType.MANUAL, source_id="abc")


def test_fk_type_requires_id():
    with pytest.raises(ValidationError):
        _Model(source_type=SourceType.PIPELINE, source_id=None)


def test_fk_type_with_id_ok():
    m = _Model(source_type=SourceType.SIMPLE_PIPELINE, source_id="abc")
    assert m.source_id == "abc"


def test_label_allowed_with_null_type():
    m = _Model(source_label="from a paper")
    assert m.source_label == "from a paper"


def test_source_type_values():
    assert {t.value for t in SourceType} == {
        "pipeline", "simple_pipeline", "analysis", "manual"
    }

# backend/src/pydantic_models/sources.py
"""Polymorphic source-provenance fields shared by material property datasets
and analyses.

A record's ``source`` records where its data came from: a pipeline run, a
simple pipeline, another analysis, or a manual upload. ``source_id`` is the id
of that row; it has no DB foreign key (the taxonomy is polymorphic), so
existence is validated in the service layer against the RLS-scoped client.
"""

from enum import StrEnum

from pydantic import model_validator

#: Source types that reference another row via ``source_id``.
FK_SOURCE_TYPES = frozenset({"pipeline", "simple_pipeline", "analysis"})


class SourceType(StrEnum):
    """Provenance kind for a material property dataset or analysis.

    This is a **closed** set (enforced by a DB CHECK), unlike the advisory
    ``analysis_type``. Adding a new member requires a migration widening the
    CHECK — deliberate, because source types are a small platform-controlled
    taxonomy rather than user-coined labels.
    """

    PIPELINE = "pipeline"
    SIMPLE_PIPELINE = "simple_pipeline"
    ANALYSIS = "analysis"
    MANUAL = "manual"


def validate_source_consistency():
    """Return a Pydantic model validator enforcing source-field consistency.

    Mirrors the DB consistency CHECK: an FK-bearing ``source_type`` requires a
    ``source_id``; ``manual`` / ``None`` forbids one. ``source_label`` is
    unconstrained. Attach as a class attribute, e.g. ``_check =
    validate_source_consistency()``.

    Returns
    -------
    classmethod
        A model-level ``after`` validator.
    """

    @model_validator(mode="after")
    def _check(self):
        stype = getattr(self, "source_type", None)
        sid = getattr(self, "source_id", None)
        stype_val = stype.value if isinstance(stype, SourceType) else stype
        if stype_val in FK_SOURCE_TYPES and not sid:
            raise ValueError(
                f"source_id is required when source_type is '{stype_val}'."
            )
        if stype_val in (None, "manual") and sid:
            raise ValueError(
                "source_id must be null when source_type is 'manual' or unset."
            )
        return self

    return _check

git add backend/src/pydantic_models/sources.py backend/tests/test_sources.py
git commit -m "feat(backend): add SourceType enum and source consistency validator"

def test_analysis_model_accepts_source_fields():
    from datetime import datetime
    from src.pydantic_models.analysis import Analysis

    a = Analysis(
        id="a1", measurement_id="m1", organization_id="o1",
        name="n", analysis_type="ecm_from_eis",
        source_type="pipeline", source_id="p1", source_label="from fit",
        created_at=datetime.now(), updated_at=datetime.now(),
    )
    assert a.source_type == "pipeline" and a.source_id == "p1"


def test_update_material_property_rejects_manual_with_id():
    import pytest
    from pydantic import ValidationError
    from src.pydantic_models.cells import UpdateMaterialPropertyDataset

    with pytest.raises(ValidationError):
        UpdateMaterialPropertyDataset(source_type="manual", source_id="x")

from src.pydantic_models.sources import SourceType, validate_source_consistency

    source_type: SourceType | None = Field(
        None, description="Provenance kind, or null if unknown."
    )
    source_id: str | None = Field(
        None, description="ID of the source row (pipeline/simple_pipeline/analysis)."
    )
    source_label: str | None = Field(
        None, description="Free-text provenance note."
    )

    _validate_source = validate_source_consistency()

    source_type: SourceType | None = Field(None, description="New provenance kind.")
    source_id: str | None = Field(None, description="New source row ID.")
    source_label: str | None = Field(None, description="New provenance note.")

    _validate_source = validate_source_consistency()

from src.pydantic_models.sources import SourceType, validate_source_consistency

    source_type: SourceType | None = Field(
        None, description="Provenance kind, or null if unknown."
    )
    source_id: str | None = Field(
        None, description="ID of the source row (pipeline/simple_pipeline/analysis)."
    )
    source_label: str | None = Field(
        None, description="Free-text provenance note."
    )

    _validate_source = validate_source_consistency()

git add backend/src/pydantic_models/cells.py backend/src/pydantic_models/analysis.py backend/tests/test_sources.py
git commit -m "feat(backend): add source fields to material property and analysis models"

# backend/tests/test_services/test_material_property_dataset_service.py
import pytest
from unittest.mock import AsyncMock, MagicMock

from src.exceptions import NotFoundError
from src.pydantic_models.sources import SourceType
from src.services.material_property_dataset_service import (
    MaterialPropertyDatasetService,
)


def _service(source_exists: bool):
    prop_repo = MagicMock()
    prop_repo.supabase = MagicMock()
    bucket_repo = MagicMock()
    svc = MaterialPropertyDatasetService(prop_repo=prop_repo, bucket_repo=bucket_repo)
    # Patch the source-repo lookups the validator dispatches to.
    fake = MagicMock() if source_exists else None
    svc._fetch_source = AsyncMock(return_value=fake)  # helper indirection
    return svc


@pytest.mark.asyncio
async def test_validate_source_manual_noop():
    svc = _service(source_exists=False)
    await svc._validate_source(SourceType.MANUAL, None)  # no raise


@pytest.mark.asyncio
async def test_validate_source_missing_raises():
    svc = _service(source_exists=False)
    with pytest.raises(NotFoundError):
        await svc._validate_source(SourceType.PIPELINE, "missing-id")


@pytest.mark.asyncio
async def test_validate_source_present_ok():
    svc = _service(source_exists=True)
    await svc._validate_source(SourceType.ANALYSIS, "an-id")  # no raise

from src.pydantic_models.sources import SourceType
from src.repositories.analysis import AnalysisRepository
from src.repositories.pipelines import PipelineRepository
from src.repositories.simple_pipelines import SimplePipelineRepository

    async def _fetch_source(self, source_type: SourceType, source_id: str):
        """Fetch a source row via a repo built from the RLS user client.

        Uses ``self.prop_repo.supabase`` (a user-scoped client) so RLS decides
        visibility — a row the caller cannot see returns ``None`` and is treated
        as absent. This is the only integrity guarantee for the polymorphic
        ``source_id`` (there is no DB foreign key).
        """
        client = self.prop_repo.supabase
        if source_type == SourceType.PIPELINE:
            return await PipelineRepository(client).get_by_id(source_id)
        if source_type == SourceType.SIMPLE_PIPELINE:
            return await SimplePipelineRepository(client).get_by_id(source_id)
        if source_type == SourceType.ANALYSIS:
            return await AnalysisRepository(client).get_analysis(source_id)
        return None

    async def _validate_source(
        self, source_type: SourceType | None, source_id: str | None
    ) -> None:
        """Raise ``NotFoundError`` if an FK-bearing source does not resolve.

        ``manual`` / ``None`` require no lookup.
        """
        if source_type is None or source_type == SourceType.MANUAL:
            return
        found = await self._fetch_source(source_type, source_id)
        if found is None:
            raise NotFoundError(source_type.value, source_id)

git add backend/src/services/material_property_dataset_service.py backend/src/routes/material_property_datasets.py backend/tests/test_services/test_material_property_dataset_service.py
git commit -m "feat(backend): validate and persist source on material property datasets"

# backend/tests/test_services/test_analysis_service.py (append if it exists)
import pytest
from unittest.mock import AsyncMock, MagicMock

from src.exceptions import NotFoundError
from src.pydantic_models.sources import SourceType
from src.services.analysis_service import AnalysisService


def _service(source_exists: bool):
    analysis_repo = MagicMock()
    analysis_repo.supabase = MagicMock()
    svc = AnalysisService(
        analysis_repo=analysis_repo,
        bucket_repo=MagicMock(),
        measurement_repo=MagicMock(),
    )
    svc._fetch_source = AsyncMock(return_value=(MagicMock() if source_exists else None))
    return svc


@pytest.mark.asyncio
async def test_analysis_validate_source_missing_raises():
    svc = _service(source_exists=False)
    with pytest.raises(NotFoundError):
        await svc._validate_source(SourceType.SIMPLE_PIPELINE, "missing")


@pytest.mark.asyncio
async def test_analysis_validate_source_manual_noop():
    svc = _service(source_exists=False)
    await svc._validate_source(SourceType.MANUAL, None)

git add backend/src/services/analysis_service.py backend/src/routes/analysis.py backend/tests/test_services/test_analysis_service.py
git commit -m "feat(backend): validate and persist source on analyses"

class SourceType(StrEnum):
    """Provenance kind for a material property dataset or analysis.

    Records where the data came from. This is a closed set on the platform;
    ``manual`` means a hand-uploaded dataset with no computed source.
    """

    PIPELINE = "pipeline"
    SIMPLE_PIPELINE = "simple_pipeline"
    ANALYSIS = "analysis"
    MANUAL = "manual"

    source_type: str | None = None
    source_id: str | None = None
    source_label: str | None = None

git add packages/ionworks-api/ionworks/models.py
git commit -m "feat(api): expose source fields and SourceType on SDK models"

  source_type: 'pipeline' | 'simple_pipeline' | 'analysis' | 'manual' | null;
  source_id: string | null;
  source_label: string | null;

// frontend/src/utils/source-link.test.ts
import { describe, it, expect } from 'vitest';
import { resolveSourceHref, sourceTypeLabel } from './source-link';
import { paths } from 'src/routes/paths';

describe('resolveSourceHref', () => {
  it('links a pipeline source to the pipeline detail page', () => {
    expect(resolveSourceHref('pipeline', 'p1', 'proj1')).toBe(
      paths.dashboard.pipelines.detail('proj1', 'p1')
    );
  });
  it('links an analysis source to the analysis detail page', () => {
    expect(resolveSourceHref('analysis', 'a1', 'proj1')).toBe(
      paths.dashboard.dataManagement.analysisDetail('proj1', 'a1')
    );
  });
  it('returns null for simple_pipeline (no detail route)', () => {
    expect(resolveSourceHref('simple_pipeline', 's1', 'proj1')).toBeNull();
  });
  it('returns null for manual / null / missing id / missing project', () => {
    expect(resolveSourceHref('manual', null, 'proj1')).toBeNull();
    expect(resolveSourceHref(null, null, 'proj1')).toBeNull();
    expect(resolveSourceHref('pipeline', 'p1', null)).toBeNull();
    expect(resolveSourceHref('pipeline', null, 'proj1')).toBeNull();
  });
});

describe('sourceTypeLabel', () => {
  it('humanizes each type', () => {
    expect(sourceTypeLabel('simple_pipeline')).toBe('Simple pipeline');
    expect(sourceTypeLabel('manual')).toBe('Manual');
    expect(sourceTypeLabel(null)).toBe('—');
  });
});

// frontend/src/utils/source-link.ts
import { paths } from 'src/routes/paths';

export type SourceType = 'pipeline' | 'simple_pipeline' | 'analysis' | 'manual';

/**
 * Resolve a provenance source to a detail-page href, or null when it cannot be
 * linked (manual/unknown source, missing id/project, or a type with no detail
 * route such as simple_pipeline). Callers render a plain label when null.
 */
export function resolveSourceHref(
  sourceType: SourceType | null,
  sourceId: string | null,
  projectId: string | null
): string | null {
  if (!sourceType || !sourceId || !projectId) return null;
  switch (sourceType) {
    case 'pipeline':
      return paths.dashboard.pipelines.detail(projectId, sourceId);
    case 'analysis':
      return paths.dashboard.dataManagement.analysisDetail(projectId, sourceId);
    default:
      return null; // simple_pipeline has no dedicated detail route; manual unreachable
  }
}

const LABELS: Record<SourceType, string> = {
  pipeline: 'Pipeline',
  simple_pipeline: 'Simple pipeline',
  analysis: 'Analysis',
  manual: 'Manual',
};

/** Human-readable label for a source type ('—' when null/unknown). */
export function sourceTypeLabel(sourceType: SourceType | null): string {
  return sourceType ? LABELS[sourceType] : '—';
}

git add frontend/src/redux/types/material-property-dataset.ts frontend/src/redux/api/analyses-api.ts frontend/src/utils/source-link.ts frontend/src/utils/source-link.test.ts
git commit -m "feat(frontend): add source fields to types and a source-link resolver"

// material-property-datasets-slice.test.ts
import { describe, it, expect } from 'vitest';
import { mockAxios, type HandlerContext } from 'src/test-utils/mock-axios';
import { makeTestStore } from 'src/test-utils/make-test-store';
import { updateMaterialPropertyDataset } from './material-property-datasets-slice';

describe('updateMaterialPropertyDataset', () => {
  it('sends source fields in the PATCH body', async () => {
    const store = makeTestStore();
    let captured: unknown;
    // onPatch(match, handler): the handler receives { url, config, body } and
    // RETURNS the raw response.data. Capture the request body in a closure.
    mockAxios.onPatch(/\/material_property_datasets\/.+/, ({ body }: HandlerContext) => {
      captured = body;
      return { id: 'd1', source_type: 'pipeline', source_id: 'p1' };
    });

    await store.dispatch(
      updateMaterialPropertyDataset({
        propertyId: 'd1',
        materialId: 'm1',
        source_type: 'pipeline',
        source_id: 'p1',
        source_label: 'from fit',
      })
    );

    // body is the OBJECT passed to axios.patch(url, body) — not a JSON string.
    expect(captured).toMatchObject({
      source_type: 'pipeline',
      source_id: 'p1',
      source_label: 'from fit',
    });
  });
});

git add frontend/src/redux/slices/model/material-property-datasets-slice.ts frontend/src/redux/slices/model/material-property-datasets-slice.test.ts
git commit -m "feat(frontend): thread source fields through the dataset update thunk"

  source_type: zod.enum(['pipeline', 'simple_pipeline', 'analysis', 'manual']).nullable(),
  source_id: zod.string().nullable(),
  source_label: zod.string().nullable(),

git add frontend/src/sections/materials/material-property-dataset-edit-dialog.tsx
git commit -m "feat(frontend): edit material property dataset source in the edit dialog"

    {
      field: 'source',
      headerName: 'Source',
      flex: 1,
      sortable: false,
      renderCell: (params) => {
        const row = params.row;
        if (!row.source_type) return <Typography variant="body2" color="text.secondary">—</Typography>;
        const href = resolveSourceHref(row.source_type, row.source_id, row.project_id);
        const label = row.source_label || sourceTypeLabel(row.source_type);
        return href ? (
          <Typography
            component={RouterLink}
            href={href}
            color="primary"
            variant="body2"
            lineHeight="inherit"
          >
            {label}
          </Typography>
        ) : (
          <Chip label={label} size="small" variant="soft" color="default" />
        );
      },
    },

git add frontend/src/sections/materials/material-detail-container.tsx
git commit -m "feat(frontend): show source column on the material datasets grid"

{analysis.source_type && (() => {
  const href = resolveSourceHref(analysis.source_type, analysis.source_id, projectId ?? null);
  const label = analysis.source_label || sourceTypeLabel(analysis.source_type);
  return (
    <Stack direction="row" spacing={1} alignItems="center">
      <Chip label={sourceTypeLabel(analysis.source_type)} size="small" variant="soft" />
      {href ? (
        <Typography component={RouterLink} href={href} color="primary" variant="body2">
          {label}
        </Typography>
      ) : (
        <Typography variant="body2" color="text.secondary">{label}</Typography>
      )}
    </Stack>
  );
})()}

git add frontend/src/sections/cell/analysis-details-container.tsx
git commit -m "feat(frontend): show read-only source on the analysis detail page"