Sep 4 - Add link relavant issues function

app/api/inspections.py

@@ -285,8 +285,8 @@ def list_inspections():
     if user.role not in _ALLOWED_ROLES:
         return api_error('Access denied', 403)
 
-    limit  = min(int(request.args.get('limit', 50)), 200)
-    offset = max(int(request.args.get('offset', 0)), 0)
+    limit  = min(request.args.get('limit',  50, type=int) or 50, 200)
+    offset = max(request.args.get('offset', 0,  type=int) or 0,  0)
 
     query = Inspection.query
 

app/api/issues.py

@@ -152,8 +152,8 @@ def list_issues():
     if user.role not in _ALLOWED_ROLES:
         return api_error('Access denied', 403)
 
-    limit  = min(int(request.args.get('limit',  100)), 200)
-    offset = max(int(request.args.get('offset', 0)),   0)
+    limit  = min(request.args.get('limit',  100, type=int) or 100, 200)
+    offset = max(request.args.get('offset', 0,   type=int) or 0,   0)
 
     query = Issue.query
 

app/api/notifications.py

@@ -73,7 +73,7 @@ def list_notifications():
     """
     user  = g.api_user
     since = _parse_since(request.args.get('since'))
-    limit = min(int(request.args.get('limit', 50)), 50)
+    limit = min(request.args.get('limit', 50, type=int) or 50, 50)
 
     def _run_orm():
         q = Notification.query.filter_by(user_id=user.id, is_read=False)

app/api/scheduled.py

@@ -118,8 +118,8 @@ def list_scheduled():
         return api_error('Access denied', 403)
 
     try:
-        limit  = min(int(request.args.get('limit',  100)), 200)
-        offset = max(int(request.args.get('offset', 0)),   0)
+        limit  = min(request.args.get('limit',  100, type=int) or 100, 200)
+        offset = max(request.args.get('offset', 0,   type=int) or 0,   0)
     except (TypeError, ValueError):
         return api_error('limit and offset must be integers', 400)
 

app/api/stats.py

@@ -111,7 +111,14 @@ def dashboard_stats():
                 )
             )
 
-    open_issues_all = open_q.all()
+    # Counts and buckets only — never a hydrated Issue. For an admin this is
+    # every open issue in the system, fetched on every iPad dashboard refresh;
+    # the full entity would drag the description TEXT and the JSON photo
+    # columns along with it. A Row exposes the same attribute names, so
+    # sla_status() below works unchanged.
+    open_issues_all = open_q.with_entities(
+        Issue.id, Issue.severity, Issue.status, Issue.reported_at
+    ).all()
     open_issues     = len(open_issues_all)
 
     # ── Severity breakdown (derived from the same open_issues_all list) ───

app/models/issue.py

@@ -43,6 +43,122 @@ class IssueFollower(db.Model):
         return f'<IssueFollower issue={self.issue_id} user={self.user_id}>'
 
 
+
+# ── Issue Link ────────────────────────────────────────────────────────────────
+# Connects two issues so staff can jump between a duplicate and the original, or
+# between issues that are simply about the same thing.
+
+class IssueLink(db.Model):
+    """One directed link between two issues, displayed on BOTH of them.
+
+    Only one row is stored per pair. The stored direction carries meaning for
+    'duplicate' — issue_id is a duplicate OF linked_issue_id — so the two issues
+    read the same row differently:
+
+        on issue_id        -> "Duplicate of #B"
+        on linked_issue_id -> "Duplicated by #A"
+
+    'related' is symmetric and reads "Related to" from either side.
+
+    Storing one row rather than a mirrored pair is what keeps the direction
+    unambiguous and makes unlinking a single delete. The cost is that uniqueness
+    cannot be expressed by the UniqueConstraint alone: (A,B) and (B,A) are
+    distinct rows to the database but the same link to a person, so the
+    duplicate check has to look in both directions. exists_between() is that
+    check, and it is the only thing callers should use.
+
+    A link is PURELY NAVIGATIONAL. Marking a duplicate does not touch either
+    issue's status, SLA, assignee or followers — closing the duplicate stays a
+    deliberate, separate action.
+
+    Multi-tenant: nothing here is tenant-aware, and deliberately so. The table
+    lives in the tenant database and every query routes through RoutingSession,
+    so a link can only ever reach an issue in the same tenant. Scope WITHIN a
+    tenant is the caller's job — see _readable_links() in routes/issues.py.
+    """
+    __tablename__ = 'issue_links'
+
+    TYPE_DUPLICATE = 'duplicate'
+    TYPE_RELATED   = 'related'
+
+    # How each link type reads from the two sides, keyed by (type, is_source).
+    LABELS = {
+        ('duplicate', True):  'Duplicate of',
+        ('duplicate', False): 'Duplicated by',
+        ('related',   True):  'Related to',
+        ('related',   False): 'Related to',
+    }
+
+    # Offered in the "Link an issue" picker. The value is what gets stored; the
+    # phrasing is from the point of view of the issue being viewed.
+    TYPE_CHOICES = [
+        ('duplicate', 'Duplicate of'),
+        ('related',   'Related to'),
+    ]
+
+    id              = db.Column(db.Integer, primary_key=True)
+    issue_id        = db.Column(db.Integer,
+                                db.ForeignKey('issues.id', ondelete='CASCADE'),
+                                nullable=False, index=True)
+    linked_issue_id = db.Column(db.Integer,
+                                db.ForeignKey('issues.id', ondelete='CASCADE'),
+                                nullable=False, index=True)
+    link_type       = db.Column(db.Enum('duplicate', 'related'),
+                                nullable=False, default='related')
+    created_by      = db.Column(db.Integer,
+                                db.ForeignKey('users.id', ondelete='SET NULL'),
+                                nullable=True)
+    created_at      = db.Column(db.DateTime, default=now_eastern, nullable=False)
+
+    __table_args__ = (
+        # Catches the exact-duplicate row at the database level. The REVERSE
+        # direction is caught by exists_between() — see the class docstring.
+        db.UniqueConstraint('issue_id', 'linked_issue_id', name='uq_issue_link'),
+    )
+
+    # BOTH relationships must pin foreign_keys: two FKs from this table to
+    # issues leave the join condition ambiguous otherwise, and the mapper raises
+    # on first ORM USE rather than at import — the app starts cleanly and then
+    # every request 500s (the phase56 lesson, CLAUDE.md §17).
+    issue        = db.relationship('Issue', foreign_keys=[issue_id],
+                                   back_populates='links_from')
+    linked_issue = db.relationship('Issue', foreign_keys=[linked_issue_id],
+                                   back_populates='links_to')
+    creator      = db.relationship('User', foreign_keys=[created_by])
+
+    def label_for(self, viewing_issue_id):
+        """How this link reads on the issue currently being viewed."""
+        return self.LABELS[(self.link_type, self.issue_id == viewing_issue_id)]
+
+    def other_issue(self, viewing_issue_id):
+        """The issue at the far end of this link from the one being viewed."""
+        return (self.linked_issue if self.issue_id == viewing_issue_id
+                else self.issue)
+
+    @staticmethod
+    def exists_between(issue_id, other_id):
+        """True when the two issues are already linked, in EITHER direction.
+
+        The UniqueConstraint only covers the stored direction, so this is what
+        stops #A being linked to #B and then #B linked back to #A as a second,
+        contradictory row.
+        """
+        return db.session.query(
+            IssueLink.query.filter(
+                db.or_(
+                    db.and_(IssueLink.issue_id == issue_id,
+                            IssueLink.linked_issue_id == other_id),
+                    db.and_(IssueLink.issue_id == other_id,
+                            IssueLink.linked_issue_id == issue_id),
+                )
+            ).exists()
+        ).scalar()
+
+    def __repr__(self):
+        return (f'<IssueLink {self.issue_id} {self.link_type} '
+                f'{self.linked_issue_id}>')
+
+
 class Issue(db.Model):
     __tablename__ = 'issues'
 
@@ -118,10 +234,37 @@ class Issue(db.Model):
     followers     = db.relationship('IssueFollower', back_populates='issue',
                                     cascade='all, delete-orphan', lazy='dynamic')
 
+    # An issue link is stored once and shown on both issues, so each issue has
+    # rows pointing OUT of it and rows pointing AT it. Deleting an issue must
+    # take its links with it from BOTH sides, or the surviving issue keeps a row
+    # referencing one that no longer exists.
+    links_from    = db.relationship('IssueLink', back_populates='issue',
+                                    foreign_keys='IssueLink.issue_id',
+                                    cascade='all, delete-orphan', lazy='dynamic')
+    links_to      = db.relationship('IssueLink', back_populates='linked_issue',
+                                    foreign_keys='IssueLink.linked_issue_id',
+                                    cascade='all, delete-orphan', lazy='dynamic')
+
     def is_followed_by(self, user):
         """Return True if the given user is currently following this issue."""
         return self.followers.filter_by(user_id=user.id).first() is not None
 
+    def all_links(self):
+        """Every link touching this issue, from both directions, newest first.
+
+        The two relationships are a storage detail — a link is one thing to the
+        person reading it, so callers get a single list and ask each row how it
+        reads via label_for() / other_issue().
+
+        Nothing here filters by permission. The caller MUST drop links whose far
+        end the viewer cannot access, or a link becomes a way to read an issue
+        at a facility they hold no assignment to. See _readable_links() in
+        routes/issues.py.
+        """
+        links = list(self.links_from) + list(self.links_to)
+        links.sort(key=lambda link: link.created_at, reverse=True)
+        return links
+
     # Display labels for handler_type. The web templates hardcode these inline;
     # this mapping exists so the mobile API can return a human-readable label
     # without the client duplicating the strings. (phase43)

app/routes/dashboard.py

@@ -17,6 +17,16 @@ bp = Blueprint('dashboard', __name__)
 logger = logging.getLogger(__name__)
 
 
+# Columns the dashboard actually reads off an issue row. The cards below need
+# counts and buckets, never a hydrated Issue — loading the full entity pulls the
+# description TEXT and three JSON photo columns for every open issue in scope,
+# on every dashboard load, and registers each one in the identity map.
+# A Row exposes the same attribute names, so the severity/handler tallies and
+# sla_status() work against these unchanged.
+_ISSUE_CARD_COLS = (Issue.id, Issue.severity, Issue.status,
+                    Issue.reported_at, Issue.handler_type)
+
+
 @bp.route('/')
 @bp.route('/dashboard')
 @login_required
@@ -100,7 +110,7 @@ def index():
             ))
 
     # Single query — derive count from the list to avoid hitting the DB twice
-    open_issues_all = open_issues_q.all()
+    open_issues_all = open_issues_q.with_entities(*_ISSUE_CARD_COLS).all()
     open_issues     = len(open_issues_all)
     severity_breakdown = {
         'critical': sum(1 for i in open_issues_all if i.severity == 'critical'),
@@ -226,7 +236,7 @@ def index():
     elif is_customer and not customer_facility_ids:
         all_open_issues = []
     else:
-        all_open_issues = sla_q.all()
+        all_open_issues = sla_q.with_entities(*_ISSUE_CARD_COLS).all()
     sla_breached = sum(1 for i in all_open_issues if sla_status(i) == 'breached')
     sla_at_risk  = sum(1 for i in all_open_issues if sla_status(i) == 'at_risk')
 

app/routes/inspections.py

@@ -254,7 +254,8 @@ def index():
         q = q.filter(Inspection.status == status_filter)
     if contract_filter.isdigit():
         _contract_fids = [
-            f.id for f in Facility.query.filter_by(project_id=int(contract_filter)).all()
+            fid for (fid,) in db.session.query(Facility.id)
+            .filter(Facility.project_id == int(contract_filter)).all()
         ]
         q = q.filter(Inspection.facility_id.in_(_contract_fids)) if _contract_fids else q.filter(False)
     if facility_filter.isdigit():
@@ -1259,7 +1260,8 @@ def export_list_pdf():
         q = q.filter(Inspection.status == status_filter)
     if contract_filter.isdigit():
         _contract_fids = [
-            f.id for f in Facility.query.filter_by(project_id=int(contract_filter)).all()
+            fid for (fid,) in db.session.query(Facility.id)
+            .filter(Facility.project_id == int(contract_filter)).all()
         ]
         q = q.filter(Inspection.facility_id.in_(_contract_fids)) if _contract_fids else q.filter(False)
     if facility_filter.isdigit():

app/routes/issues.py

@@ -6,7 +6,7 @@ from flask import (Blueprint, render_template, redirect, url_for,
                    flash, request, current_app, jsonify, abort, Response)
 from flask_login import login_required, current_user
 from app import db
-from app.models.issue import Issue, IssueComment, IssueFollower
+from app.models.issue import Issue, IssueComment, IssueFollower, IssueLink
 from app.models.facility import Facility, Area
 from app.models.user import User
 from app.models.notification import (
@@ -71,6 +71,48 @@ class _SLAFilteredPage:
         return iter([1])
 
 
+# ── Issue read access ─────────────────────────────────────────────────────────
+# One definition of "may this person open this issue", used by the detail view,
+# by the linked-issues panel, and by the link picker's search. They must not
+# drift: the picker is what a person searches, but the panel is what actually
+# renders another issue's description, and the POST is the real boundary.
+#
+# All three are WITHIN one tenant. Cross-tenant isolation is not their job and
+# never can be — RoutingSession has already bound the session to g.tenant's
+# database, so an id from another tenant simply does not resolve here.
+
+def _viewer_facility_scope(user):
+    """Facility ids this user is confined to, or None when unrestricted.
+
+    Returns a LIST (possibly empty) for the two scoped role groups and None for
+    everyone else. Empty list and None mean opposite things — [] is "no access
+    to anything", None is "no restriction" — so callers must test `is None`
+    rather than truthiness (CLAUDE.md rule 57's failure mode).
+    """
+    if user.is_inspector:                       # rule 87 — never role == 'inspector'
+        return get_inspector_scope(user) or []
+    if user.role == 'customer':                 # rule 99 — capability check, exact match
+        return get_customer_scope(user) or []
+    return None
+
+
+def _issue_in_scope(issue, scope_ids):
+    """Whether one issue falls inside an already-resolved facility scope.
+
+    Takes the scope rather than the user so a caller filtering a list of issues
+    resolves it once instead of re-querying the assignment tables per row.
+    """
+    if scope_ids is None:
+        return True
+    facility = issue.resolved_facility
+    return facility is not None and facility.id in scope_ids
+
+
+def _issue_readable_by(issue, user):
+    """Single-issue convenience wrapper around the two helpers above."""
+    return _issue_in_scope(issue, _viewer_facility_scope(user))
+
+
 def _assignee_label(user):
     """Dropdown label for an assignee.
 
@@ -146,13 +188,14 @@ def export_list_pdf():
             date_to_filter = ''
     if contract_filter.isdigit():
         _contract_fids = [
-            f.id for f in Facility.query.filter_by(project_id=int(contract_filter)).all()
+            fid for (fid,) in db.session.query(Facility.id)
+            .filter(Facility.project_id == int(contract_filter)).all()
         ]
         q = q.filter(db.or_(
             Issue.facility_id.in_(_contract_fids),
             Area.facility_id.in_(_contract_fids),
         )) if _contract_fids else q.filter(False)
-    if facility_filter:
+    if facility_filter.isdigit():
         fid = int(facility_filter)
         q = q.filter(db.or_(Issue.facility_id == fid, Area.facility_id == fid))
     if reporter_filter.isdigit():
@@ -181,7 +224,7 @@ def export_list_pdf():
         p = db.session.get(Project, int(contract_filter))
         if p:
             filter_parts.append(f'Contract: {p.name}')
-    if facility_filter:
+    if facility_filter.isdigit():
         f = db.session.get(Facility, int(facility_filter))
         if f:
             filter_parts.append(f'Facility: {f.name}')
@@ -279,7 +322,8 @@ def index():
             date_to_filter = ''
     if contract_filter.isdigit():
         _contract_fids = [
-            f.id for f in Facility.query.filter_by(project_id=int(contract_filter)).all()
+            fid for (fid,) in db.session.query(Facility.id)
+            .filter(Facility.project_id == int(contract_filter)).all()
         ]
         q = q.filter(db.or_(
             Issue.facility_id.in_(_contract_fids),
@@ -287,7 +331,7 @@ def index():
         )) if _contract_fids else q.filter(False)
     if reporter_filter.isdigit():
         q = q.filter(Issue.reported_by == int(reporter_filter))
-    if facility_filter:
+    if facility_filter.isdigit():
         fid = int(facility_filter)
         q = q.filter(
             db.or_(
@@ -325,8 +369,9 @@ def index():
     # can render the following badge and inline unfollow button without an
     # additional query per row.
     followed_ids = {
-        f.issue_id
-        for f in IssueFollower.query.filter_by(user_id=current_user.id).all()
+        iid for (iid,) in
+        db.session.query(IssueFollower.issue_id)
+        .filter(IssueFollower.user_id == current_user.id).all()
     }
 
     # Facilities for the filter dropdown — scoped for inspectors/customers,
@@ -398,18 +443,14 @@ def view(issue_id):
     if issue is None:
         abort(404)
 
-    if current_user.is_inspector:
-        fids     = get_inspector_scope(current_user)
-        facility = issue.resolved_facility
-        if not fids or not facility or facility.id not in fids:
-            flash('Access denied.', 'danger')
-            return redirect(url_for('issues.index'))
+    # Scope gate — see _issue_readable_by(). This was two inline blocks that the
+    # linked-issues panel would have had to reproduce a third time; it is now
+    # one definition so the panel cannot end up more permissive than the page.
+    if not _issue_readable_by(issue, current_user):
+        flash('Access denied.', 'danger')
+        return redirect(url_for('issues.index'))
+
     if current_user.role == 'customer':
-        cids = get_customer_scope(current_user) or []
-        facility = issue.resolved_facility
-        if not facility or facility.id not in cids:
-            flash('Access denied.', 'danger')
-            return redirect(url_for('issues.index'))
         if request.method == 'POST':
             # Customers may only add a comment, and only on issues they follow or reported
             can_comment = (issue.is_followed_by(current_user) or issue.reported_by == current_user.id)
@@ -686,7 +727,209 @@ def view(issue_id):
                            form=form,
                            comments=comments,
                            comments_open=comments_open,
-                           is_following=is_following)
+                           is_following=is_following,
+                           # Already filtered to links whose far end this viewer
+                           # may open — see _readable_links().
+                           issue_links=_readable_links(issue, current_user),
+                           link_types=IssueLink.TYPE_CHOICES,
+                           can_manage_links=_can_manage_links(issue, current_user))
+
+
+# ── Issue links ───────────────────────────────────────────────────────────────
+# Connect a duplicate to its original, or two issues about the same thing, so
+# whoever picks one up can reach the other. Links are purely navigational: they
+# never touch status, SLA, assignee or followers on either issue.
+
+def _can_manage_links(issue, user):
+    """Who may add or remove a link on this issue.
+
+    Deliberately the SAME set as the page's `can_edit` (the Update Issue panel):
+    admin / director / auditor, or the person the issue is assigned to. Keeping
+    the two identical means the panel's buttons and this gate cannot disagree —
+    the alternative is a second, slightly different rule that nobody remembers.
+    Widening it (to project_manager, or to the reporter) is a one-line change
+    here, but change `can_edit` in issues/view.html at the same time.
+    """
+    return (user.role in ('admin', 'director', 'auditor')
+            or issue.assigned_to == user.id)
+
+
+def _readable_links(issue, user):
+    """Links on this issue whose FAR END the viewer may also open.
+
+    A link is a pointer to another issue's id, description and facility, so an
+    unfiltered panel would let a customer read an issue at a facility they have
+    no assignment to simply because one of our staff linked it. The scope is
+    resolved once for the whole list rather than per row.
+
+    Returns a list of (link, other_issue, label) ready for the template.
+    """
+    scope = _viewer_facility_scope(user)
+    visible = []
+    for link in issue.all_links():
+        other = link.other_issue(issue.id)
+        if other is None or not _issue_in_scope(other, scope):
+            continue
+        visible.append((link, other, link.label_for(issue.id)))
+    return visible
+
+
+@bp.route('/<int:issue_id>/links', methods=['POST'])
+@login_required
+def add_link(issue_id):
+    """Link this issue to another one."""
+    issue = db.session.get(Issue, issue_id)
+    if issue is None:
+        abort(404)
+    if not _issue_readable_by(issue, current_user):
+        abort(403)
+    if not _can_manage_links(issue, current_user):
+        abort(403)
+
+    link_type = request.form.get('link_type', '')
+    if link_type not in (IssueLink.TYPE_DUPLICATE, IssueLink.TYPE_RELATED):
+        flash('Choose how the two issues are related.', 'warning')
+        return redirect(_view_url(issue_id))
+
+    raw_target = (request.form.get('linked_issue_id') or '').strip().lstrip('#')
+    if not raw_target.isdigit():
+        flash('Enter the number of the issue to link, e.g. 412.', 'warning')
+        return redirect(_view_url(issue_id))
+    target_id = int(raw_target)
+
+    if target_id == issue.id:
+        flash('An issue cannot be linked to itself.', 'warning')
+        return redirect(_view_url(issue_id))
+
+    target = db.session.get(Issue, target_id)
+    # A 404 and a 403 are the same message here on purpose: whether an issue
+    # outside your scope EXISTS is not something the link box should confirm.
+    if target is None or not _issue_readable_by(target, current_user):
+        flash(f'Issue #{target_id} was not found.', 'warning')
+        return redirect(_view_url(issue_id))
+
+    if IssueLink.exists_between(issue.id, target.id):
+        flash(f'Issue #{issue.id} and #{target.id} are already linked.', 'info')
+        return redirect(_view_url(issue_id))
+
+    link = IssueLink(
+        issue_id        = issue.id,
+        linked_issue_id = target.id,
+        link_type       = link_type,
+        created_by      = current_user.id,
+    )
+    db.session.add(link)
+    db.session.commit()
+
+    log_action(ACTION_UPDATE, 'Issue', issue.id, f'#{issue.id}',
+               f'linked to #{target.id} as {link_type}')
+    current_app.logger.info(
+        'ISSUE LINK | issue_id=%s | linked_issue_id=%s | type=%s | user=%s',
+        issue.id, target.id, link_type, current_user.username,
+    )
+    flash(f'Issue #{issue.id} is now linked to #{target.id}.', 'success')
+    return redirect(_view_url(issue_id))
+
+
+@bp.route('/<int:issue_id>/links/<int:link_id>/delete', methods=['POST'])
+@login_required
+def remove_link(issue_id, link_id):
+    """Remove a link. Either end of it may do this."""
+    issue = db.session.get(Issue, issue_id)
+    if issue is None:
+        abort(404)
+    if not _issue_readable_by(issue, current_user):
+        abort(403)
+    if not _can_manage_links(issue, current_user):
+        abort(403)
+
+    link = db.session.get(IssueLink, link_id)
+    # The link must actually touch THIS issue. Without the check, anyone able to
+    # manage links on any one issue could delete a link between two others by
+    # posting its id here.
+    if link is None or issue.id not in (link.issue_id, link.linked_issue_id):
+        flash('That link no longer exists.', 'info')
+        return redirect(_view_url(issue_id))
+
+    other_id = link.linked_issue_id if link.issue_id == issue.id else link.issue_id
+    db.session.delete(link)
+    db.session.commit()
+
+    log_action(ACTION_UPDATE, 'Issue', issue.id, f'#{issue.id}',
+               f'unlinked from #{other_id}')
+    current_app.logger.info(
+        'ISSUE UNLINK | issue_id=%s | linked_issue_id=%s | user=%s',
+        issue.id, other_id, current_user.username,
+    )
+    flash(f'Removed the link to issue #{other_id}.', 'info')
+    return redirect(_view_url(issue_id))
+
+
+@bp.route('/<int:issue_id>/link-search')
+@login_required
+def link_search(issue_id):
+    """JSON candidates for the link picker.
+
+    Scoped exactly like the issue list, so an inspector or customer can only
+    find issues they could already open — searching must not become a way to
+    enumerate another contract's issues. The results are a convenience; the POST
+    in add_link() re-checks access and is the real boundary.
+    """
+    issue = db.session.get(Issue, issue_id)
+    if issue is None:
+        abort(404)
+    if not _issue_readable_by(issue, current_user):
+        abort(403)
+
+    term = (request.args.get('q') or '').strip().lstrip('#')
+    if len(term) < 1:
+        return jsonify({'results': []})
+
+    q = (
+        Issue.query
+        .outerjoin(Area, Issue.area_id == Area.id)
+        .options(joinedload(Issue.facility), contains_eager(Issue.area))
+        .filter(Issue.id != issue.id)
+    )
+
+    scope = _viewer_facility_scope(current_user)
+    if scope is not None:
+        if not scope:
+            return jsonify({'results': []})
+        q = q.filter(db.or_(
+            Issue.facility_id.in_(scope),
+            db.and_(Issue.area_id.isnot(None), Area.facility_id.in_(scope)),
+        ))
+
+    # Exclude issues already linked in either direction — offering them only
+    # produces an "already linked" flash.
+    linked_ids = {other.id for _l, other, _lbl in _readable_links(issue, current_user)}
+    if linked_ids:
+        q = q.filter(Issue.id.notin_(linked_ids))
+
+    if term.isdigit():
+        # A number is almost always an issue number, so match the id first and
+        # fall back to the description for things like "Room 204".
+        q = q.filter(db.or_(Issue.id == int(term),
+                            Issue.description.ilike(f'%{term}%')))
+    else:
+        q = q.filter(Issue.description.ilike(f'%{term}%'))
+
+    matches = q.order_by(Issue.reported_at.desc()).limit(10).all()
+
+    return jsonify({'results': [
+        {
+            'id':          i.id,
+            'description': (i.description or '')[:110],
+            'status':      (i.status or '').replace('_', ' ').title(),
+            'severity':    (i.severity or '').title(),
+            'location':    (i.area.name if i.area
+                            else i.resolved_facility.name if i.resolved_facility
+                            else '—'),
+            'reported_at': i.reported_at.strftime('%Y-%m-%d') if i.reported_at else '',
+        }
+        for i in matches
+    ]})
 
 
 # ── Follow ────────────────────────────────────────────────────────────────────

app/routes/reports.py

@@ -74,23 +74,29 @@ def index():
     if current_user.role in ('admin', 'director', 'project_manager'):
         inspector_filter = request.args.get('inspector_id', type=int) or None
 
-    # Pre-compute inspection ID sets used by _scope_issue to avoid join conflicts.
-    inspector_inspection_ids = []   # own inspections (inspector role)
-    filter_inspection_ids    = None # filtered inspector's inspections (admin/dir/PM)
+    # Scope issues by the relevant inspector's inspections, as a SUBQUERY rather
+    # than a materialised id list. The previous form pulled every inspection id
+    # that inspector had ever performed into Python and sent them straight back
+    # as a literal IN (1, 2, 3, ... N): the round trip is wasted, the statement
+    # grows without bound with the inspector's history, and a long enough list
+    # eventually trips max_allowed_packet. A subquery is also still a single
+    # statement, so the "avoid join conflicts" reason for pre-computing holds.
+    #
+    # IN (empty subquery) already matches nothing, so the explicit empty-list
+    # guards the old code needed are gone rather than merely moved.
+    inspector_insp_subq = None
     if is_inspector:
-        inspector_inspection_ids = [
-            row[0] for row in
+        inspector_insp_subq = (
             db.session.query(Inspection.id)
             .filter(Inspection.inspector_id == current_user.id)
-            .all()
-        ]
+            .scalar_subquery()
+        )
     elif inspector_filter:
-        filter_inspection_ids = [
-            row[0] for row in
+        inspector_insp_subq = (
             db.session.query(Inspection.id)
             .filter(Inspection.inspector_id == inspector_filter)
-            .all()
-        ]
+            .scalar_subquery()
+        )
 
     def _scope_insp(q):
         if is_inspector:
@@ -104,14 +110,8 @@ def index():
         return q
 
     def _scope_issue(q):
-        if is_inspector:
-            if not inspector_inspection_ids:
-                return q.filter(False)
-            return q.filter(Issue.inspection_id.in_(inspector_inspection_ids))
-        if filter_inspection_ids is not None:
-            if not filter_inspection_ids:
-                return q.filter(False)
-            return q.filter(Issue.inspection_id.in_(filter_inspection_ids))
+        if inspector_insp_subq is not None:
+            return q.filter(Issue.inspection_id.in_(inspector_insp_subq))
         if customer_facility_ids is not None:
             if not customer_facility_ids:
                 return q.filter(False)

app/templates/issues/view.html

@@ -227,6 +227,84 @@
       </div>
     </div>
 
+    {# ── Linked issues ──────────────────────────────────────────────────────
+       Duplicates and related issues, so whoever picks this one up can reach the
+       others. `issue_links` arrives already filtered to links whose far end this
+       viewer may open (_readable_links) — do NOT add links from the model
+       directly here, or a customer sees an issue at a facility they have no
+       assignment to. Links are navigational only: nothing here changes status,
+       SLA, assignee or followers on either issue. #}
+    <div class="card shadow-sm mb-4" id="linked-issues-section">
+      <div class="card-header bg-light d-flex justify-content-between align-items-center">
+        <h6 class="mb-0">
+          <i class="bi bi-link-45deg me-1"></i>Linked Issues
+          <span class="badge bg-secondary rounded-pill ms-1">{{ issue_links|length }}</span>
+        </h6>
+        {% if can_manage_links %}
+        <button type="button" class="btn btn-sm btn-outline-primary"
+                data-bs-toggle="modal" data-bs-target="#linkIssueModal">
+          <i class="bi bi-plus-lg me-1"></i>Link an Issue
+        </button>
+        {% endif %}
+      </div>
+
+      <div class="card-body py-2">
+        {% if issue_links %}
+        <div class="list-group list-group-flush">
+          {% for link, other, label in issue_links %}
+          <div class="list-group-item px-0 py-2 d-flex align-items-start gap-2 flex-wrap">
+            <span class="badge {{ 'bg-warning text-dark' if link.link_type == 'duplicate' else 'bg-info text-dark' }} mt-1"
+                  style="min-width:7.5rem;">{{ label }}</span>
+
+            <div class="flex-grow-1" style="min-width:14rem;">
+              <a href="{{ url_for('issues.view', issue_id=other.id, next=back_url) }}"
+                 class="fw-semibold text-decoration-none">#{{ other.id }}</a>
+              <span class="text-muted small ms-1">
+                {{ other.area.name if other.area
+                   else other.resolved_facility.name if other.resolved_facility else '—' }}
+              </span>
+              <div class="small text-muted text-truncate" style="max-width:38rem;">
+                {{ other.description }}
+              </div>
+            </div>
+
+            <div class="d-flex align-items-center gap-1 mt-1">
+              <span class="badge bg-{{ 'danger' if other.severity in ['critical','high']
+                                       else 'warning text-dark' if other.severity == 'medium'
+                                       else 'secondary' }}">{{ other.severity|title }}</span>
+              <span class="badge bg-{{ 'success' if other.status == 'resolved'
+                                       else 'info text-dark' if other.status == 'pending_verification'
+                                       else 'light text-dark' }}">
+                {{ other.status|replace('_',' ')|title }}
+              </span>
+              {% if can_manage_links %}
+              <form method="POST" class="mb-0 ms-1"
+                    action="{{ url_for('issues.remove_link', issue_id=issue.id, link_id=link.id) }}"
+                    onsubmit="return confirm('Remove the link between #{{ issue.id }} and #{{ other.id }}? Neither issue is changed or deleted.');">
+                <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
+                <input type="hidden" name="next" value="{{ back_url }}">
+                <button type="submit" class="btn btn-sm btn-link text-muted p-0 px-1"
+                        title="Remove this link">
+                  <i class="bi bi-x-lg"></i>
+                </button>
+              </form>
+              {% endif %}
+            </div>
+          </div>
+          {% endfor %}
+        </div>
+        {% else %}
+        <p class="text-muted small mb-0 py-1">
+          <i class="bi bi-info-circle me-1"></i>
+          No linked issues.
+          {% if can_manage_links %}
+          Use <strong>Link an Issue</strong> to point at a duplicate or a related issue.
+          {% endif %}
+        </p>
+        {% endif %}
+      </div>
+    </div>
+
     {# ── Comments ───────────────────────────────────────────────────────── #}
     <div class="card shadow-sm mb-4" id="comments-section">
       <div class="card-header bg-light d-flex justify-content-between align-items-center">
@@ -564,6 +642,77 @@
   {% endif %}
 </div>
 
+{# ── Link an issue ────────────────────────────────────────────────────────────
+   Search is scoped server-side to issues this viewer could already open, so the
+   picker can never be used to enumerate another contract's issues. The POST
+   re-checks access — the search is only a convenience. #}
+{% if can_manage_links %}
+<div class="modal fade" id="linkIssueModal" tabindex="-1"
+     aria-labelledby="linkIssueModalLabel" aria-hidden="true">
+  <div class="modal-dialog modal-dialog-centered">
+    <div class="modal-content">
+      <form method="POST" action="{{ url_for('issues.add_link', issue_id=issue.id) }}">
+        <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
+        <input type="hidden" name="next" value="{{ back_url }}">
+
+        <div class="modal-header">
+          <h5 class="modal-title" id="linkIssueModalLabel">
+            <i class="bi bi-link-45deg me-1"></i>Link an issue to #{{ issue.id }}
+          </h5>
+          <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+        </div>
+
+        <div class="modal-body">
+          <div class="mb-3">
+            <label class="form-label small fw-semibold" for="linkTypeSelect">
+              How are they related?
+            </label>
+            <select name="link_type" id="linkTypeSelect" class="form-select form-select-sm">
+              {% for value, label in link_types %}
+              <option value="{{ value }}">
+                #{{ issue.id }} is a <strong>{{ label|lower }}</strong> …
+              </option>
+              {% endfor %}
+            </select>
+            <div class="form-text">
+              Linking is for navigation only — neither issue's status, SLA or
+              assignee changes.
+            </div>
+          </div>
+
+          <div class="mb-2">
+            <label class="form-label small fw-semibold" for="linkIssueSearch">
+              Which issue?
+            </label>
+            <input type="text" class="form-control form-control-sm" id="linkIssueSearch"
+                   autocomplete="off" placeholder="Issue number, or words from the description…">
+            <input type="hidden" name="linked_issue_id" id="linkIssueId">
+          </div>
+
+          {# Chosen issue, shown once picked so nobody submits a mistyped number #}
+          <div id="linkIssueChosen" class="alert alert-primary py-2 small d-none mb-2">
+            <span id="linkIssueChosenText"></span>
+            <button type="button" class="btn btn-sm btn-link p-0 ms-2" id="linkIssueClear">change</button>
+          </div>
+
+          <div id="linkIssueResults" class="list-group small" style="max-height:16rem; overflow-y:auto;"></div>
+          <div id="linkIssueEmpty" class="text-muted small d-none py-2">
+            No matching issue you can access.
+          </div>
+        </div>
+
+        <div class="modal-footer">
+          <button type="button" class="btn btn-secondary btn-sm" data-bs-dismiss="modal">Cancel</button>
+          <button type="submit" class="btn btn-primary btn-sm" id="linkIssueSubmit" disabled>
+            <i class="bi bi-link-45deg me-1"></i>Link Issue
+          </button>
+        </div>
+      </form>
+    </div>
+  </div>
+</div>
+{% endif %}
+
 {% if current_user.role in ['admin', 'director'] %}
 <div class="modal fade" id="deleteIssueModal" tabindex="-1" aria-labelledby="deleteIssueModalLabel" aria-hidden="true">
   <div class="modal-dialog modal-dialog-centered">
@@ -619,6 +768,122 @@
             section.scrollIntoView({ behavior: 'smooth', block: 'start' });
         }
     }
+    // ── Link-an-issue picker ────────────────────────────────────────────────
+    // Type a number or some words, pick from the scoped results, submit. The
+    // hidden linked_issue_id is only ever set by CHOOSING a result, so the
+    // number posted is always one the server just confirmed this user can see.
+    //
+    // Every result field is written with textContent / createTextNode, never
+    // innerHTML: `description` is text a person typed and would otherwise be
+    // an XSS hole straight into the page of whoever opens the picker.
+    var linkSearch = document.getElementById('linkIssueSearch');
+    if (linkSearch) {
+        var linkResults    = document.getElementById('linkIssueResults');
+        var linkEmpty      = document.getElementById('linkIssueEmpty');
+        var linkIdField    = document.getElementById('linkIssueId');
+        var linkChosen     = document.getElementById('linkIssueChosen');
+        var linkChosenText = document.getElementById('linkIssueChosenText');
+        var linkClear      = document.getElementById('linkIssueClear');
+        var linkSubmit     = document.getElementById('linkIssueSubmit');
+        var searchTimer    = null;
+        var searchSeq      = 0;
+
+        function clearChoice() {
+            linkIdField.value = '';
+            linkSubmit.disabled = true;
+            linkChosen.classList.add('d-none');
+            linkSearch.classList.remove('d-none');
+        }
+
+        function choose(item) {
+            linkIdField.value = item.id;
+            linkSubmit.disabled = false;
+            linkChosenText.textContent =
+                '#' + item.id + ' — ' + item.location + ' — ' + item.description;
+            linkChosen.classList.remove('d-none');
+            linkSearch.classList.add('d-none');
+            linkResults.innerHTML = '';
+            linkEmpty.classList.add('d-none');
+        }
+
+        function renderResults(items) {
+            linkResults.innerHTML = '';
+            linkEmpty.classList.toggle('d-none', items.length > 0);
+
+            items.forEach(function (item) {
+                var row = document.createElement('button');
+                row.type = 'button';
+                row.className = 'list-group-item list-group-item-action py-2';
+
+                var head = document.createElement('div');
+                head.className = 'd-flex justify-content-between gap-2';
+
+                var num = document.createElement('span');
+                num.className = 'fw-semibold';
+                num.textContent = '#' + item.id + ' · ' + item.location;
+
+                var meta = document.createElement('span');
+                meta.className = 'text-muted';
+                meta.textContent = item.severity + ' · ' + item.status +
+                                   (item.reported_at ? ' · ' + item.reported_at : '');
+
+                head.appendChild(num);
+                head.appendChild(meta);
+
+                var desc = document.createElement('div');
+                desc.className = 'text-muted text-truncate';
+                desc.textContent = item.description;
+
+                row.appendChild(head);
+                row.appendChild(desc);
+                row.addEventListener('click', function () { choose(item); });
+                linkResults.appendChild(row);
+            });
+        }
+
+        function runSearch() {
+            var term = linkSearch.value.trim();
+            if (!term) {
+                linkResults.innerHTML = '';
+                linkEmpty.classList.add('d-none');
+                return;
+            }
+            // Responses can arrive out of order; only the newest one may render.
+            var seq = ++searchSeq;
+            fetch('{{ url_for("issues.link_search", issue_id=issue.id) }}?q=' +
+                  encodeURIComponent(term), { headers: { 'Accept': 'application/json' } })
+                .then(function (res) { return res.ok ? res.json() : { results: [] }; })
+                .then(function (data) {
+                    if (seq !== searchSeq) { return; }
+                    renderResults(data.results || []);
+                })
+                .catch(function () {
+                    if (seq !== searchSeq) { return; }
+                    renderResults([]);
+                });
+        }
+
+        linkSearch.addEventListener('input', function () {
+            clearTimeout(searchTimer);
+            searchTimer = setTimeout(runSearch, 250);
+        });
+        // The picker lives inside a form — Enter would submit it with no issue
+        // chosen instead of searching.
+        linkSearch.addEventListener('keydown', function (ev) {
+            if (ev.key === 'Enter') {
+                ev.preventDefault();
+                clearTimeout(searchTimer);
+                runSearch();
+            }
+        });
+        linkClear.addEventListener('click', function () {
+            clearChoice();
+            linkSearch.value = '';
+            linkSearch.focus();
+        });
+    }
+
+
 })();
 </script>
 {% endblock %}

app/utils/scope.py

@@ -18,6 +18,7 @@ that no facility-level scoping is required (full access applies).
 """
 
 import logging
+from app import db
 from app.models.project import CustomerAssignment
 from app.models.facility import Facility
 
@@ -43,30 +44,34 @@ def get_customer_scope(user) -> list[int] | None:
     if user.role != 'customer':
         return None  # no scoping needed for internal staff
 
-    assignments = CustomerAssignment.query.filter_by(user_id=user.id).all()
+    # Select only the two columns needed. The previous .all() built full
+    # CustomerAssignment ORM objects (and their identity-map entries) purely to
+    # read two integers off each one; this function runs on nearly every
+    # request for a customer, sometimes more than once.
+    assignments = db.session.query(
+        CustomerAssignment.project_id,
+        CustomerAssignment.facility_id,
+    ).filter(CustomerAssignment.user_id == user.id).all()
 
     if not assignments:
         return []
 
     # Separate direct facility assignments from project-level assignments
-    direct_facility_ids = {a.facility_id for a in assignments if a.facility_id}
-    project_ids         = {a.project_id  for a in assignments if not a.facility_id}
+    direct_facility_ids = {fac_id for _, fac_id in assignments if fac_id}
+    project_ids         = {proj_id for proj_id, fac_id in assignments if not fac_id}
 
     facility_ids = set(direct_facility_ids)
 
     # Single bulk query for all project-scoped facilities — replaces the
-    # previous per-assignment Facility.query loop (N+1 pattern).
+    # previous per-assignment Facility.query loop (N+1 pattern). Only the id
+    # column is read; nothing here needs a hydrated Facility.
     if project_ids:
-        project_facilities = (
-            Facility.query
-            .filter(
+        facility_ids.update(
+            fid for (fid,) in db.session.query(Facility.id).filter(
                 Facility.project_id.in_(project_ids),
                 Facility.active == True,
-            )
-            .all()
+            ).all()
         )
-        for f in project_facilities:
-            facility_ids.add(f.id)
 
     logger.debug(
         'SCOPE | customer_scope | user_id=%s username=%s facility_ids=%s',
@@ -102,16 +107,19 @@ def get_inspector_scope(user) -> list[int] | None:
 
     from app.models.inspector_assignment import InspectorAssignment
 
+    # Column-only selects — see the note in get_customer_scope(). This runs on
+    # every scoped request for both inspector roles.
     project_ids = [
-        a.project_id
-        for a in InspectorAssignment.query.filter_by(user_id=user.id).all()
+        pid for (pid,) in
+        db.session.query(InspectorAssignment.project_id)
+        .filter(InspectorAssignment.user_id == user.id).all()
     ]
 
     if not project_ids:
         return []  # strict: no assignments = no access
 
     facility_ids = [
-        f.id for f in Facility.query.filter(
+        fid for (fid,) in db.session.query(Facility.id).filter(
             Facility.project_id.in_(project_ids),
             Facility.active == True,
         ).all()

app/utils/sla.py

@@ -110,11 +110,38 @@ def send_sla_alerts():
 
     logger = logging.getLogger(__name__)
 
-    # yield_per streams rows in batches of 100 rather than loading all open
-    # issues into memory at once.  At current scale this is a no-op difference,
-    # but it prevents a memory spike if the issue count grows large.
+    # Narrow to actual CANDIDATES in SQL rather than reading every open issue
+    # and deciding in Python. This runs every 30 minutes forever, so the old
+    # form's cost grew with the whole open-issue backlog even on a quiet night
+    # where nothing was due. Three filters, each mirroring a `continue` below:
+    #
+    #   1. reported_at IS NOT NULL — the column is nullable, and sla_status()
+    #      raises TypeError on a NULL (datetime + timedelta). One such row
+    #      would abort the entire cron run, so exclude it in SQL.
+    #   2. sla_notified <> 'breached' — the highest level is already sent; the
+    #      loop skips these unconditionally.
+    #   3. old enough to be at least at-risk for its OWN severity, i.e.
+    #      reported_at <= now - (window * 0.75). A critical issue qualifies
+    #      after 3h, a low one after 90h.
+    #
+    # Anything this excludes would have hit a `continue` anyway, so the set of
+    # notifications sent is unchanged — only the rows read are.
+    now = now_eastern()
+    age_clauses = [
+        db.and_(
+            Issue.severity == severity,
+            Issue.reported_at <= now - timedelta(hours=hours * AT_RISK_THRESHOLD),
+        )
+        for severity, hours in SLA_HOURS.items()
+    ]
+
+    # yield_per streams the survivors in batches rather than materialising them
+    # all at once.
     open_issues = Issue.query.filter(
-        Issue.status.in_(['open', 'in_progress', 'pending_verification'])
+        Issue.status.in_(['open', 'in_progress', 'pending_verification']),
+        Issue.reported_at.isnot(None),
+        db.or_(Issue.sla_notified.is_(None), Issue.sla_notified != 'breached'),
+        db.or_(*age_clauses),
     ).yield_per(100)
 
     total_sent = 0