From 58a2198a92adfa5ac28366cad84bad9b1c63dc77 Mon Sep 17 00:00:00 2001
From: warlock20 <kiranmathews20@gmail.com>
Date: Tue, 21 Jul 2026 18:22:45 +0200
Subject: [PATCH] feat: Implement unique company ticker constraint per user and
 enhance company identity handling

---
 app/companies/api_routes.py                   | 104 +++++++++-----
 app/models/company.py                         |   6 +
 app/portfolio/templates/add_transaction.html  |  71 ++++++++++
 app/portfolio/transactions.py                 |  83 ++++++-----
 .../financial_data/financial_data_service.py  |  43 +++++-
 app/services/financial_data/providers/base.py |   7 +
 .../financial_data/providers/yahoo_finance.py |   4 +
 app/services/transaction_service.py           |  14 ++
 app/utils/company_identity.py                 | 133 ++++++++++++++++++
 .../unique_company_ticker_per_user.py         |  71 ++++++++++
 10 files changed, 462 insertions(+), 74 deletions(-)
 create mode 100644 app/utils/company_identity.py
 create mode 100644 migrations/versions/unique_company_ticker_per_user.py

diff --git a/app/companies/api_routes.py b/app/companies/api_routes.py
index 63d549d..64d53a1 100644
--- a/app/companies/api_routes.py
+++ b/app/companies/api_routes.py
@@ -24,6 +24,7 @@
 from app.services.financial_data import FinancialDataService
 from app.companies import companies_bp
 from app.utils.ticker_validator import TickerValidator
+from app.utils.company_identity import company_identity_key
 from app.services.currency_service import CurrencyService
 from app.utils.response_utils import json_error, json_not_found
 from app.utils.time_utils import now_utc
@@ -40,6 +41,18 @@ def get_financial_service():
         _financial_service = FinancialDataService()
     return _financial_service
 
+def _serialize_user_company(company):
+    """Shape a Company the user owns for the search response."""
+    return {
+        'id': company.id,
+        'name': company.name,
+        'ticker_symbol': company.ticker_symbol,
+        'industry': company.industry,
+        'sector': company.sector.display_name if company.sector else None,
+        'source': 'existing'
+    }
+
+
 @companies_bp.route('/api/companies/search')
 @login_required
 def api_search_companies():
@@ -70,34 +83,56 @@ def api_search_companies():
         db.or_(*search_conditions)
     ).order_by(Company.name).limit(10).all()
 
-    user_company_data = []
-    for company in user_companies:
-        user_company_data.append({
-            'id': company.id,
-            'name': company.name,
-            'ticker_symbol': company.ticker_symbol,
-            'industry': company.industry,
-            'sector': company.sector.display_name if company.sector else None,
-            'source': 'existing'
-        })
+    user_company_data = [_serialize_user_company(c) for c in user_companies]
+    listed_company_ids = {c['id'] for c in user_company_data}
+
+    # Identity of every company the user already owns. The ticker saved on the
+    # company is the user's own choice of exchange, so a provider listing of the
+    # same company under any other ticker is a duplicate, not a new company.
+    owned_rows = db.session.query(
+        Company.id, Company.name, Company.ticker_symbol
+    ).filter(Company.user_id == current_user.id).all()
+
+    owned_company_ids = {}
+    for company_id, name, ticker in owned_rows:
+        owned_company_ids.setdefault(company_identity_key(name, ticker), company_id)
+
+    def claim_owned_company(identity):
+        """
+        Resolve a provider listing against the user's own companies.
+
+        Returns True when the company is already owned, in which case it is
+        surfaced under the user's saved ticker rather than offered again. A
+        user who saved Microsoft as MSF.F and then searches "MSFT" must still
+        see their own holding, otherwise the UI offers to create a duplicate.
+        """
+        company_id = owned_company_ids.get(identity)
+        if company_id is None:
+            return False
+
+        if company_id not in listed_company_ids:
+            listed_company_ids.add(company_id)
+            user_company_data.append(
+                _serialize_user_company(db.session.get(Company, company_id))
+            )
+        return True
 
     # Try financial data service lookup - both by ticker AND by company name
     yahoo_suggestions = []
+    suggested_identities = set()
     service = get_financial_service()
 
     # 1. If query is a valid ticker, look it up directly
     if normalized_ticker:
         try:
-            # Check if this ticker already exists for the user
-            existing = Company.query.filter_by(
-                ticker_symbol=normalized_ticker,
-                user_id=current_user.id
-            ).first()
+            info = service.get_ticker_info(normalized_ticker)
 
-            if not existing:
-                info = service.get_ticker_info(normalized_ticker)
+            if info and info.get('name'):
+                identity = company_identity_key(info.get('name'), normalized_ticker)
 
-                if info and info.get('name'):
+                # Skip if the user already owns this company, under any ticker
+                if not claim_owned_company(identity):
+                    suggested_identities.add(identity)
                     yahoo_suggestions.append({
                         'ticker_symbol': normalized_ticker,
                         'name': info.get('name'),
@@ -113,29 +148,26 @@ def api_search_companies():
     # 2. Search by company name (if not a ticker or no results from ticker search)
     if len(query) >= 3 and len(yahoo_suggestions) == 0:
         try:
-            search_results = service.search_companies(query, max_results=5)
+            # The service already collapses cross-listings to one row per company
+            search_results = service.search_companies(query, max_results=3)
 
-            for result in search_results[:3]:
+            for result in search_results:
                 ticker_symbol = result.get('ticker_symbol')
+                name = result.get('name') or ticker_symbol
 
-                if not ticker_symbol:
+                identity = company_identity_key(name, ticker_symbol)
+                if identity in suggested_identities or claim_owned_company(identity):
                     continue
 
-                # Skip if user already has this company
-                existing = Company.query.filter_by(
-                    ticker_symbol=ticker_symbol,
-                    user_id=current_user.id
-                ).first()
-
-                if not existing:
-                    yahoo_suggestions.append({
-                        'ticker_symbol': ticker_symbol,
-                        'name': result.get('name') or ticker_symbol,
-                        'industry': result.get('industry') or '',
-                        'sector': result.get('sector') or '',
-                        'summary': '',
-                        'source': 'financial_data_service'
-                    })
+                suggested_identities.add(identity)
+                yahoo_suggestions.append({
+                    'ticker_symbol': ticker_symbol,
+                    'name': name,
+                    'industry': result.get('industry') or '',
+                    'sector': result.get('sector') or '',
+                    'summary': '',
+                    'source': 'financial_data_service'
+                })
         except Exception as e:
             logger.debug(f'Company search failed: {e}')
             pass
diff --git a/app/models/company.py b/app/models/company.py
index 93551cf..2a41eb3 100644
--- a/app/models/company.py
+++ b/app/models/company.py
@@ -37,6 +37,12 @@ class Company(db.Model):
     journey_notes = db.Column(db.Text, nullable=True)
     journey_notes_updated_at = db.Column(db.DateTime, nullable=True)
 
+    __table_args__ = (
+        # One company per ticker per user. Application-level guards existed on
+        # every creation path but duplicates still got through.
+        db.UniqueConstraint('user_id', 'ticker_symbol', name='uq_company_user_ticker'),
+    )
+
     # Relationships
     sector = db.relationship("Sector", backref="companies")
 
diff --git a/app/portfolio/templates/add_transaction.html b/app/portfolio/templates/add_transaction.html
index 81eff8e..d140205 100644
--- a/app/portfolio/templates/add_transaction.html
+++ b/app/portfolio/templates/add_transaction.html
@@ -97,6 +97,7 @@ <h1>Add Transaction</h1>
                                 endif %} {% if form_data and form_data.company_id|int==company.id %}selected{% endif
                                 %}
                                 data-has-position="{% if company.id in existing_positions %}true{% else %}false{% endif %}"
+                                data-ever-held="{% if company.id in held_company_ids %}true{% else %}false{% endif %}"
                                 data-position-shares="{% if company.id in existing_positions %}{{ existing_positions[company.id].shares }}{% endif %}"
                                 data-position-cost="{% if company.id in existing_positions %}{{ existing_positions[company.id].avg_cost }}{% endif %}"
                                 data-ticker="{{ company.ticker_symbol }}">
@@ -111,6 +112,11 @@ <h1>Add Transaction</h1>
                                 onclick="event.preventDefault(); openCompanyModal(handleCompanySelection);"
                                 class="text-primary">Add a new company</a>
                         </div>
+                        {# Kept after the link above: handleCompanySelection targets the
+                           first .form-text in this block to flash its success message. #}
+                        <div class="form-text" id="companyFilterHint" style="display: none;">
+                            <i class="bi bi-funnel me-1"></i><span id="companyFilterHintText"></span>
+                        </div>
                     </div>
 
                     <!-- Currency Selection (Auto-detected from ticker) -->
@@ -462,8 +468,14 @@ <h6 class="card-title">Transaction Types</h6>
             option.text = `${company.ticker_symbol} - ${company.name}`;
             option.setAttribute('data-ticker', company.ticker_symbol);
             option.setAttribute('data-has-position', 'false');
+            option.setAttribute('data-ever-held', 'false');
             option.selected = true;
             companySelect.add(option);
+
+            // Keep the filter snapshot in sync, or the next type change drops it
+            if (allCompanyOptions !== null) {
+                allCompanyOptions.push(option);
+            }
         }
 
         // Trigger change event to update currency and other related fields
@@ -587,8 +599,67 @@ <h6 class="card-title">Transaction Types</h6>
     }
 
     // Update labels and field visibility based on transaction type
+    // ============================================================
+    // COMPANY LIST FILTERING BY TRANSACTION TYPE
+    // ============================================================
+    // Only a company you have held can have paid you a dividend, and only one
+    // you currently own can be sold. Watchlist companies are hidden for those
+    // types so the list shows what is actually actionable.
+
+    let allCompanyOptions = null;
+
+    function companyAllowedForType(option, transactionType) {
+        if (!option.value) return true;  // keep the "Select a company..." placeholder
+        if (transactionType === 'DIVIDEND') return option.dataset.everHeld === 'true';
+        if (transactionType === 'SELL') return option.dataset.hasPosition === 'true';
+        return true;
+    }
+
+    function filterCompaniesByType() {
+        const companySelect = document.getElementById('company_id');
+        const checkedType = document.querySelector('input[name="type"]:checked');
+        if (!companySelect || !checkedType) return;
+
+        // Snapshot the full list once, before any filtering removes options
+        if (allCompanyOptions === null) {
+            allCompanyOptions = Array.from(companySelect.options);
+        }
+
+        const transactionType = checkedType.value;
+        const previousValue = companySelect.value;
+        const allowed = allCompanyOptions.filter(o => companyAllowedForType(o, transactionType));
+
+        // Rebuild rather than hide: browsers disagree on whether a hidden
+        // <option> remains selectable.
+        companySelect.replaceChildren(...allowed);
+
+        // Drop a selection the new type does not permit
+        const stillValid = allowed.some(o => o.value === previousValue);
+        companySelect.value = stillValid ? previousValue : '';
+
+        const hint = document.getElementById('companyFilterHint');
+        const hintText = document.getElementById('companyFilterHintText');
+        const hiddenCount = allCompanyOptions.length - allowed.length;
+
+        if (hiddenCount > 0) {
+            const shown = allowed.length - 1;  // exclude the placeholder
+            hintText.textContent = (transactionType === 'DIVIDEND')
+                ? `Showing ${shown} ${shown === 1 ? 'company' : 'companies'} you have held — only these can pay a dividend.`
+                : `Showing ${shown} ${shown === 1 ? 'company' : 'companies'} you currently own — only these can be sold.`;
+            hint.style.display = 'block';
+        } else {
+            hint.style.display = 'none';
+        }
+
+        // Let currency/position handlers react to a cleared selection
+        if (!stillValid && previousValue) {
+            companySelect.dispatchEvent(new Event('change'));
+        }
+    }
+
     function updateLabels() {
         const transactionType = document.querySelector('input[name="type"]:checked').value;
+        filterCompaniesByType();
         const quantityLabel = document.getElementById('quantityLabel');
         const priceLabel = document.getElementById('priceLabel');
         const expectationsSection = document.getElementById('buy_expectations_section');
diff --git a/app/portfolio/transactions.py b/app/portfolio/transactions.py
index 6cbad35..2b6a773 100644
--- a/app/portfolio/transactions.py
+++ b/app/portfolio/transactions.py
@@ -252,6 +252,52 @@ def force_resync():
         
     return redirect(url_for('portfolio.dashboard'))
 
+def _add_transaction_context():
+    """
+    Build the template context for the add-transaction form.
+
+    Shared by the initial GET and the re-render that follows a validation
+    warning, so the form behaves identically on both paths. Previously the
+    re-render passed only `companies`, which silently disabled the
+    add-to-position UI after a warning.
+    """
+    companies = Company.query.filter_by(
+        user_id=current_user.id
+    ).order_by(Company.name).all()
+
+    # A PortfolioPosition row survives a full exit, so its mere existence means
+    # the user held the company at some point. Only the shares differ.
+    existing_positions = {}
+    held_company_ids = set()
+    positions = PortfolioPosition.query.filter_by(user_id=current_user.id).all()
+    for pos in positions:
+        held_company_ids.add(pos.company_id)
+        if pos.total_shares > 0:
+            existing_positions[pos.company_id] = {
+                'shares': pos.total_shares,
+                'avg_cost': float(pos.average_cost_basis) if pos.average_cost_basis else 0,
+                'ticker': pos.company.ticker_symbol
+            }
+
+    # Check which companies have research
+    companies_with_research = set()
+    research_projects = ResearchProject.query.filter_by(user_id=current_user.id).all()
+    for rp in research_projects:
+        companies_with_research.add(rp.company_id)
+
+    return {
+        'companies': companies,
+        'existing_positions': existing_positions,
+        # Dividends need a company held at some point; sells need shares now.
+        'held_company_ids': held_company_ids,
+        'owned_company_ids': set(existing_positions.keys()),
+        'companies_with_research': companies_with_research,
+        'preselected_company_id': request.args.get('company_id', type=int),
+        'user_currency': current_user.base_currency,
+        'currency_symbol': CurrencyService.get_currency_symbol(current_user.base_currency),
+    }
+
+
 @portfolio_bp.route('/transaction/new', methods=['GET', 'POST'])
 @portfolio_bp.route('/transaction/add', methods=['GET', 'POST'])
 @login_required
@@ -281,52 +327,19 @@ def add_transaction():
             flash(result.error, 'error')
             # Re-render form with warnings if validation failed
             if result.warnings:
-                companies = Company.query.filter_by(user_id=current_user.id).order_by(Company.name).all()
                 return render_template('add_transaction.html',
-                                      companies=companies,
                                       warnings=result.warnings,
                                       show_warning=True,
                                       form_data=request.form,
-                                      user_currency=current_user.base_currency,
-                                      currency_symbol=CurrencyService.get_currency_symbol(current_user.base_currency))
+                                      **_add_transaction_context())
             return redirect(url_for('portfolio.add_transaction'))
 
     # GET request - show form
-    companies = Company.query.filter_by(user_id=current_user.id).order_by(Company.name).all()
-
-    # Get existing positions for the user
-    existing_positions = {}
-    positions = PortfolioPosition.query.filter_by(user_id=current_user.id).all()
-    for pos in positions:
-        if pos.total_shares > 0:
-            existing_positions[pos.company_id] = {
-                'shares': pos.total_shares,
-                'avg_cost': float(pos.average_cost_basis) if pos.average_cost_basis else 0,
-                'ticker': pos.company.ticker_symbol
-            }
-
-    # Check which companies have research
-    companies_with_research = set()
-    research_projects = ResearchProject.query.filter_by(user_id=current_user.id).all()
-    for rp in research_projects:
-        companies_with_research.add(rp.company_id)
-
-    # Get company_id from query params if provided
-    preselected_company_id = request.args.get('company_id', type=int)
-
-    user_currency = current_user.base_currency
-    currency_symbol = CurrencyService.get_currency_symbol(user_currency)
-
     return render_template('add_transaction.html',
-                          companies=companies,
                           warnings=warnings,
                           show_warning=False,
                           form_data=None,
-                          existing_positions=existing_positions,
-                          companies_with_research=companies_with_research,
-                          preselected_company_id=preselected_company_id,
-                          user_currency=user_currency,
-                          currency_symbol=currency_symbol)
+                          **_add_transaction_context())
 
 @portfolio_bp.route('/transaction/<int:transaction_id>/edit', methods=['GET', 'POST'])
 @login_required
diff --git a/app/services/financial_data/financial_data_service.py b/app/services/financial_data/financial_data_service.py
index c9e5385..acf513f 100644
--- a/app/services/financial_data/financial_data_service.py
+++ b/app/services/financial_data/financial_data_service.py
@@ -38,6 +38,7 @@
     CachedFinancialDataProvider
 )
 from app.services.currency_service import CurrencyService
+from app.utils.company_identity import company_identity_key, is_tradeable_equity
 
 logger = logging.getLogger(__name__)
 
@@ -263,11 +264,17 @@ def get_ticker_info(self, ticker: str) -> Optional[Dict[str, Any]]:
 
     def search_companies(self, query: str, max_results: int = 5) -> list[Dict[str, Any]]:
         """
-        Search for companies by name or ticker.
+        Search for companies by name or ticker, one entry per company.
+
+        Providers return every listing they know of, so a search for
+        "Microsoft" comes back as MSFT, MSF.F, MSFT.NE, ZMSF.NE and a tokenized
+        crypto product -- which read as duplicates to a user. This collapses
+        them to the company's primary listing and drops instruments that are
+        not equity in the company itself.
 
         Args:
             query: Search query (company name or partial ticker)
-            max_results: Maximum number of results to return
+            max_results: Maximum number of companies to return
 
         Returns:
             List of company info dicts, each containing:
@@ -276,8 +283,38 @@ def search_companies(self, query: str, max_results: int = 5) -> list[Dict[str, A
             - exchange: Exchange name (optional)
             - sector: Sector (optional)
             - industry: Industry (optional)
+            - quote_type: Instrument type, e.g. 'EQUITY' (optional)
+            - score: Provider relevance score, higher is better (optional)
         """
-        return self.provider.search_companies(query, max_results)
+        # Over-fetch: collapsing cross-listings can discard most of a page of
+        # results, and we still want max_results distinct companies.
+        raw_results = self.provider.search_companies(query, max_results * 4)
+
+        companies = []
+        seen_identities = set()
+
+        for result in raw_results:
+            if not result.get('ticker_symbol'):
+                continue
+
+            if not is_tradeable_equity(result):
+                continue
+
+            identity = company_identity_key(
+                result.get('name'), result.get('ticker_symbol')
+            )
+            if not identity or identity in seen_identities:
+                continue
+
+            # Providers return results in relevance order, so the first listing
+            # seen for a company is its primary one.
+            seen_identities.add(identity)
+            companies.append(result)
+
+            if len(companies) >= max_results:
+                break
+
+        return companies
 
     def get_batch_current_prices(self, tickers: List[str]) -> Dict[str, Optional[Dict[str, Any]]]:
         """
diff --git a/app/services/financial_data/providers/base.py b/app/services/financial_data/providers/base.py
index ba69974..57fa6de 100644
--- a/app/services/financial_data/providers/base.py
+++ b/app/services/financial_data/providers/base.py
@@ -175,6 +175,11 @@ def search_companies(self, query: str, max_results: int = 5) -> list[Dict[str, A
             query: Search query (company name or partial ticker)
             max_results: Maximum number of results to return
 
+        Returns raw provider results, which routinely include several listings
+        of the same company (cross-listings, depositary receipts) as well as
+        non-equity instruments. Callers should use
+        FinancialDataService.search_companies, which collapses these.
+
         Returns:
             List of company info dicts, each containing:
             - ticker_symbol: Stock ticker
@@ -182,6 +187,8 @@ def search_companies(self, query: str, max_results: int = 5) -> list[Dict[str, A
             - exchange: Exchange name (optional)
             - sector: Sector (optional)
             - industry: Industry (optional)
+            - quote_type: Instrument type, e.g. 'EQUITY', 'ETF' (optional)
+            - score: Provider relevance score, higher is better (optional)
         """
         pass
 
diff --git a/app/services/financial_data/providers/yahoo_finance.py b/app/services/financial_data/providers/yahoo_finance.py
index c104328..42e324b 100644
--- a/app/services/financial_data/providers/yahoo_finance.py
+++ b/app/services/financial_data/providers/yahoo_finance.py
@@ -491,6 +491,10 @@ def search_companies(self, query: str, max_results: int = 5) -> list[Dict[str, A
                         'exchange': result.get('exchange') or result.get('exchDisp'),
                         'sector': result.get('sector') or result.get('sectorDisp'),
                         'industry': result.get('industry') or result.get('industryDisp'),
+                        # Callers need these to tell a company's primary listing
+                        # apart from cross-listings, ETFs and depositary receipts.
+                        'quote_type': result.get('quoteType'),
+                        'score': result.get('score'),
                     })
 
             # Restore logging level
diff --git a/app/services/transaction_service.py b/app/services/transaction_service.py
index 6d4c4d7..aa3844f 100644
--- a/app/services/transaction_service.py
+++ b/app/services/transaction_service.py
@@ -201,6 +201,20 @@ def validate_transaction_data(
                     error_message=f'Cannot sell {quantity} shares. You only own {owned_shares} shares of {company.ticker_symbol}'
                 )
 
+        # A dividend can only come from a company the user has held. The form
+        # hides the others, but that is client-side only.
+        if transaction_type == 'DIVIDEND':
+            position = PortfolioPosition.query.filter_by(
+                user_id=user_id,
+                company_id=company_id
+            ).first()
+
+            if not position:
+                return TransactionValidationResult(
+                    is_valid=False,
+                    error_message=f'Cannot record a dividend for {company.ticker_symbol}. You have never held shares in it'
+                )
+
         return TransactionValidationResult(is_valid=True)
 
     @staticmethod
diff --git a/app/utils/company_identity.py b/app/utils/company_identity.py
new file mode 100644
index 0000000..5769954
--- /dev/null
+++ b/app/utils/company_identity.py
@@ -0,0 +1,133 @@
+# StartWithA
+# Copyright (C) 2024-2026 Kiran Mathews
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""
+Company identity matching.
+
+A single company is listed under many tickers: the primary listing, foreign
+cross-listings, and depositary receipts. Yahoo Finance returns all of them for
+one query, so `Microsoft` yields MSFT, MSF.F, MSFT.NE and ZMSF.NE -- four rows
+that read as the same company to a user.
+
+Matching on the ticker string alone cannot collapse these, because the tickers
+are genuinely different. These helpers derive a stable identity from the company
+name instead, so cross-listings can be recognised as one company.
+"""
+
+import re
+
+# Corporate form suffixes carry no identifying information -- "Apple Inc." and
+# "APPLE INC" are the same company.
+#
+# Only true legal forms belong here. Words like GROUP or HOLDINGS are part of
+# the trade name and distinguish real companies from one another, so stripping
+# them would wrongly merge "Reliance Group" into "Reliance, Inc.".
+_LEGAL_SUFFIXES = [
+    'INCORPORATED', 'CORPORATION', 'COMPANY', 'LIMITED',
+    'INC', 'CORP', 'LTD', 'PLC', 'LLC', 'LP',
+    'NV', 'SA', 'AG', 'SE', 'AB', 'ASA', 'OYJ', 'SPA', 'BV',
+]
+
+_LEGAL_SUFFIX_RE = re.compile(
+    r'\s+(?:' + '|'.join(_LEGAL_SUFFIXES) + r')\.?$'
+)
+
+# Parenthesised qualifiers describe the instrument, not the company:
+# "MICROSOFT CDR (CAD HEDGED)", "APPLE INC CEDEAR(REPR 1/20 SHR)".
+_PARENTHETICAL_RE = re.compile(r'\([^)]*\)?')
+
+_PUNCTUATION_RE = re.compile(r'[^A-Z0-9 ]+')
+_WHITESPACE_RE = re.compile(r'\s+')
+
+# Wrapper instruments that track a company without being a listing of it.
+# ADRs are deliberately absent: for many foreign companies the ADR is the only
+# practical way for a user to hold the stock, so it is a legitimate result.
+_DERIVATIVE_RE = re.compile(
+    r'\b(?:CEDEAR|CDRS?|TOKENIZED|XSTOCK|WARRANTS?|RIGHTS)\b'
+)
+
+# Yahoo returns ETFs, indices, options and crypto alongside equities. Only
+# equities can be held as a company position in a portfolio.
+_EQUITY_QUOTE_TYPE = 'EQUITY'
+
+
+def normalize_company_name(name):
+    """
+    Reduce a company name to a comparable core.
+
+    "Microsoft Corporation", "MICROSOFT CORP." and "Microsoft Corporation "
+    all reduce to "MICROSOFT".
+
+    Returns an empty string when nothing identifying survives.
+    """
+    if not name:
+        return ''
+
+    normalized = _PARENTHETICAL_RE.sub(' ', name.upper())
+    normalized = _PUNCTUATION_RE.sub(' ', normalized)
+    normalized = _WHITESPACE_RE.sub(' ', normalized).strip()
+
+    # Repeat: "Reliance Industries Ltd. Inc" carries two stackable suffixes.
+    previous = None
+    while previous != normalized:
+        previous = normalized
+        normalized = _LEGAL_SUFFIX_RE.sub('', normalized).strip()
+
+    return normalized
+
+
+def base_ticker(ticker_symbol):
+    """
+    Strip the exchange suffix from a ticker: "MSFT.NE" -> "MSFT".
+
+    Used only as a fallback identity when a listing has no usable name.
+    """
+    if not ticker_symbol:
+        return ''
+    return ticker_symbol.upper().split('.')[0].strip()
+
+
+def company_identity_key(name, ticker_symbol=None):
+    """
+    Build a key that is equal for two listings of the same company.
+
+    The normalized name is the identity. The base ticker is only a fallback,
+    because distinct companies routinely share a base ticker across exchanges
+    (India's RELIANCE.NS versus an unrelated US RELIANCE would collide).
+    """
+    normalized = normalize_company_name(name)
+    if normalized:
+        return normalized
+    return base_ticker(ticker_symbol)
+
+
+def is_tradeable_equity(result):
+    """
+    Whether a provider search result is a real equity listing of a company.
+
+    Rejects non-equity instruments (ETFs, crypto, indices) and wrapper
+    instruments such as CDRs and CEDEARs, which duplicate a company the user
+    can already reach through its ordinary listing.
+    """
+    quote_type = (result.get('quote_type') or '').upper()
+    if quote_type and quote_type != _EQUITY_QUOTE_TYPE:
+        return False
+
+    name = (result.get('name') or '').upper()
+    if _DERIVATIVE_RE.search(name):
+        return False
+
+    return True
diff --git a/migrations/versions/unique_company_ticker_per_user.py b/migrations/versions/unique_company_ticker_per_user.py
new file mode 100644
index 0000000..66dd6b4
--- /dev/null
+++ b/migrations/versions/unique_company_ticker_per_user.py
@@ -0,0 +1,71 @@
+# StartWithA
+# Copyright (C) 2024-2026 Kiran Mathews
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""unique company ticker per user
+
+Nothing at the database level stopped a user from ending up with two Company
+rows for the same ticker, and in practice that happened: one row accumulated
+the transactions while an identical twin sat empty beside it, showing up as a
+duplicate in every company dropdown.
+
+Application code guards against this on each creation path, but a guard in the
+application cannot be relied upon across concurrent requests or future paths.
+This makes it impossible.
+
+Revision ID: unique_company_ticker
+Revises: 644ee0c924cf
+Create Date: 2026-07-21
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = 'unique_company_ticker'
+down_revision = '644ee0c924cf'
+branch_labels = None
+depends_on = None
+
+CONSTRAINT_NAME = 'uq_company_user_ticker'
+
+
+def upgrade():
+    # Duplicates must be resolved before this can apply. Fail with a message
+    # that says what to do rather than a bare IntegrityError.
+    conn = op.get_bind()
+    duplicates = conn.execute(sa.text("""
+        SELECT user_id, ticker_symbol, count(*) AS n
+        FROM company
+        GROUP BY user_id, ticker_symbol
+        HAVING count(*) > 1
+    """)).fetchall()
+
+    if duplicates:
+        detail = ', '.join(f'user {d.user_id}/{d.ticker_symbol} x{d.n}' for d in duplicates[:10])
+        raise RuntimeError(
+            f'Cannot add {CONSTRAINT_NAME}: {len(duplicates)} duplicate '
+            f'(user_id, ticker_symbol) group(s) still exist -- {detail}. '
+            'Merge or remove the duplicates before running this migration.'
+        )
+
+    op.create_unique_constraint(
+        CONSTRAINT_NAME, 'company', ['user_id', 'ticker_symbol']
+    )
+
+
+def downgrade():
+    op.drop_constraint(CONSTRAINT_NAME, 'company', type_='unique')