fix: Avoid foreign key violation on span table with topological sort

[erichare]

This pull request improves the reliability and correctness of span insertion into the database by ensuring parent spans are always inserted before their children, which is necessary for PostgreSQL's foreign key enforcement. It introduces new helper methods for resolving and sorting spans, and adds comprehensive tests to validate this behavior and handle edge cases like cycles.

Core improvements to span insertion order:

• Refactored _flush_to_database in native.py to pre-compute UUIDs for spans and perform a topological sort, ensuring that parent spans are inserted before their children, preventing foreign key violations in PostgreSQL.
• Added _resolve_span_uuids and _topological_sort_spans helper methods to encapsulate UUID resolution and topological sorting logic for spans, including cycle detection and safe handling of unresolvable dependencies.

Testing and validation:

• Added the TestTopologicalSortSpans test class to verify correct sorting of spans in various scenarios, including no parents, nested spans, cycles, and self-parenting.
• Added the TestFlushParentChildOrder test class to ensure that the database merge order respects parent-before-child insertion, even when spans are provided out of order.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8319c2c8-2de0-454f-9b25-0e896c857c6b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-foreign-key-backport

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Frontend Unit Test Coverage Report

Coverage Summary

Lines	Statements	Branches	Functions
	23.49% (8246/35103)	16.2% (4466/27557)	16.26% (1200/7376)

Unit Test Results

Tests	Skipped	Failures	Errors	Time
2723	0 💤	0 ❌	0 🔥	45.065s ⏱️

[Adam-Aghili]

LGTM

Tested general functionality traces for LLM and agent component and checked for previously discoverd bugs. Did not find any.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 37.42%. Comparing base (0a6f7e0) to head (910aa42).
⚠️ Report is 1 commits behind head on release-1.8.2.

❌ Your project status has failed because the head coverage (41.63%) is below the target coverage (60.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@                Coverage Diff                @@
##           release-1.8.2   #12242      +/-   ##
=================================================
+ Coverage          37.39%   37.42%   +0.02%     
=================================================
  Files               1592     1593       +1     
  Lines              78364    78398      +34     
  Branches           11890    11890              
=================================================
+ Hits               29308    29341      +33     
  Misses             47384    47384              
- Partials            1672     1673       +1     

Flag	Coverage Δ
backend	57.69% <100.00%> (+0.07%)	⬆️
frontend	21.05% <ø> (ø)
lfx	41.63% <ø> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...c/backend/base/langflow/services/tracing/native.py	95.75% <100.00%> (+3.66%)	⬆️
...end/base/langflow/services/tracing/span_sorting.py	100.00% <100.00%> (ø)

... and 12 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Cristhianzl]

Summary

This PR fixes a real PostgreSQL foreign key violation when child spans are inserted before their parents. It introduces two new methods (_resolve_span_uuids and _topological_sort_spans) and comprehensive tests.

---

🔴 CRITICAL: Security & PII

PII in Logs - ZERO TOLERANCE

• No email addresses in logs
• No user names in logs
• No phone numbers in logs
• No addresses in logs
• No PII in webhook messages
• No print() / console.log() with user data
• No PII in any logging call

The only new log is a logger.warning that reports the count of affected spans — no PII.

General Security

• All user inputs are sanitized and validated at system boundaries
• No secrets/credentials in code
• No internal details exposed in error messages to end users
• External/untrusted data is never trusted without validation
• SQL queries use parameterized statements (uses SQLAlchemy ORM session.merge)
• No hardcoded API keys, tokens, or passwords
• Sensitive data is not stored in plain text

Result: ✅ PASS

---

🔴 CRITICAL: DRY Principle

• Types/Models: No duplicate type definitions
• Classes: No duplicate class implementations
• Functions: UUID resolution logic was previously inline in _flush_to_database — the PR correctly extracts it into _resolve_span_uuids, eliminating duplication
• Constants: No duplicate constant definitions
• Validation: No duplicate validation logic
• API calls: N/A

Result: ✅ PASS

---

🔴 CRITICAL: File Structure Limits

Hard Limits Per File — native.py

Metric	Maximum Allowed	Value After PR	Status
Lines of code (excl. imports, types, docs)	300	~633	❌ VIOLATION
Functions with DIFFERENT responsibilities	5	13+	❌ VIOLATION
Functions with SAME responsibility	10	N/A	✅ OK
Main classes per file	1	1 (NativeTracer)	✅ OK
Small related classes	5	0	✅ OK

Note: The file was already in violation before this PR (559 lines, 11 methods). The PR adds +74 net lines and 2 new methods without any structural refactoring.

Methods in native.py after PR (13 total, 6+ different responsibility categories):

Responsibility	Methods
Orchestration	add_trace, end_trace, end, wait_for_flush
Data Persistence	_flush_to_database
Formatting/Serialization	_build_completed_span, _resolve_span_uuids
Parsing/Sorting	_topological_sort_spans, _map_trace_type
External Communication	get_langchain_callback, add_langchain_span, end_langchain_span
Configuration	_is_enabled

Mixed prefixes in same file: add_*, end_*, _flush_*, _build_*, get_*, _resolve_*, _topological_sort_*, _map_*, _is_*

Hard Limits Per File — test_native_tracer.py

Metric	Maximum Allowed	Value After PR	Status
Lines of code	300	~606	❌ VIOLATION

Single Responsibility Test

Can you describe native.py in ONE sentence WITHOUT "and" or "or"?

• ❌ "Manages tracing and resolves span UUIDs and performs topological sorting and persists to database and manages LangChain callbacks"

Coesion — Over-Engineering Check

The two new methods are NOT over-engineering:

• _resolve_span_uuids has ~25 lines of real logic, testable in isolation
• _topological_sort_spans has ~30 lines of real logic, is @staticmethod, has its own tests
• Both are used by _flush_to_database and could be imported from another module

✅ Extraction is justified — but they should live in separate files per the rules.

Result: ❌ FAIL — 3 hard limit violations

---

🟠 IMPORTANT: Architecture & Structure

Single Responsibility Principle

• Each file has ONE clear responsibility — ❌ native.py has 6+ responsibilities
• Each function does ONE thing — new methods are well-focused
• Each class has ONE reason to change — debatable given mixed concerns
• No function names with "and", "or", "then", or vague "process"
• No monolithic files that "do everything" — ❌ native.py is monolithic

Layer Separation

• No business logic in controllers/handlers
• No HTTP concerns in service layer
• Repository operations are within DB session scope

Recommended File Structure

services/tracing/
├── native.py                → Orchestration: add_trace, end_trace, end, wait_for_flush
├── native_callback.py       → (already exists) callback handler
├── native_persistence.py    → Data Persistence: _flush_to_database, _resolve_span_uuids
├── span_sorting.py          → Sorting: _topological_sort_spans (@staticmethod, reusable)
└── formatting.py            → (already exists) safe_int_tokens

Result: ❌ FAIL

---

🟠 IMPORTANT: Code Quality

SOLID Principles

• SRP: ❌ File has 6+ responsibilities
• OCP: New methods are additive
• LSP: N/A
• ISP: N/A
• DIP: N/A

Clean Code

• Strong typing: Explicit type annotations on parameters and return values
• Early returns: Present in topological sort (cycle detection break)
• No magic values: No magic numbers/strings introduced
• Naming: _resolve_span_uuids and _topological_sort_spans are descriptive and intention-revealing
• Immutability: ⚠️ span_data["parent_span_id"] = None mutates the original dict in-place during cycle handling — may cause unexpected side effects if completed_spans is accessed after the sort

Specific Code Issues

Issue 1 — In-place mutation of original data (_topological_sort_spans):

if isinstance(span_data, dict):
    span_data["parent_span_id"] = None

This modifies self.completed_spans in-place. If any downstream code relies on parent_span_id after flush, it will see inconsistent data. Should create a copy or use a new dict.

Issue 2 — Redundant local import (_resolve_span_uuids):

from uuid import UUID as UUID_

UUID is already imported at the top of the file (from uuid import UUID, uuid5). The local import creates an unnecessary alias. Same issue exists in _flush_to_database.

Result: ⚠️ PARTIAL PASS — 2 issues to address

---

🟠 IMPORTANT: Error Handling

• Expected errors are handled explicitly — cycles detected and handled with warning
• No silent failures — logger.warning on cycle detection
• Errors include meaningful context — warning message includes count of affected spans
• Clear distinction between recoverable errors and fatal exceptions — cycle is treated as recoverable (breaks parent relationship), not as exception
• Inputs validated at system boundaries — invalid UUIDs handled via uuid5 fallback

Result: ✅ PASS

---

🟡 RECOMMENDED: Observability

• Structured logging at key decision points — logger.warning on cycle
• Appropriate log levels — warning is correct for abnormal but recoverable situation
• NO sensitive data in logs — only span count is logged
• No redundant logs

Result: ✅ PASS

---

🟡 RECOMMENDED: Comments

• No comments explaining WHAT — comments explain WHY (PostgreSQL FK enforcement)
• Comments only explain WHY — non-obvious decisions documented
• No commented-out code
• Docstrings on new methods are explanatory and relevant

Result: ✅ PASS

---

🟢 TESTING

Coverage Requirements

• Unit tests for core logic — TestTopologicalSortSpans covers the algorithm
• Success cases — test_no_parents, test_child_after_parent, test_deep_nesting
• Error cases — test_cycle_two_node, test_self_parent_span
• Edge cases — test_empty_input, test_parent_outside_batch
• Invalid inputs — ❌ No test for _resolve_span_uuids with string parent IDs (non-UUID)

Test Quality

• Clear test names: test_child_after_parent, test_deep_nesting, test_cycle_two_node
• Independent tests — each test generates its own UUIDs
• Deterministic tests
• External dependencies mocked — TestFlushParentChildOrder uses AsyncMock for session
• Tests validate behavior, not implementation
• Clear Arrange-Act-Assert structure

Test Issues

Issue 3 — Incorrect patch path (test_flush_inserts_parent_before_child):
The test patches lfx.services.deps.session_scope, but the import in native.py is from lfx.services.deps import session_scope. If the module has already resolved the import, the patch may not work correctly. The patch should target langflow.services.tracing.native.session_scope (the module that uses the import).

Issue 4 — Missing test for _resolve_span_uuids:
This method has significant branching logic (valid UUID vs invalid, parent as UUID instance vs string) that is not tested in isolation.

Result: ⚠️ PARTIAL PASS — 2 issues

---

🟢 LEGACY CODE AWARENESS

• Not prolonging bad patterns — the extraction of methods is a step in the right direction
• New code is cleanly structured internally
• ❌ Does not address the pre-existing structural debt in native.py

Result: ⚠️ PARTIAL PASS

---

📋 Final Checklist

🔴 CRITICAL (Blockers)
[x] No PII in any logs, prints, or webhook messages
[x] No secrets/credentials in code
[x] No duplicate types, classes, or logic (DRY)
[ ] No file exceeds 300 lines                                    ❌ native.py ~633, test ~606
[ ] No file has more than 5 functions with DIFFERENT responsibilities  ❌ native.py has 6+ categories
[x] No file has more than 10 functions even with same responsibility
[x] No file has more than 1 main class
[ ] No mixed responsibility prefixes in same file                 ❌ add_*, end_*, _flush_*, _build_*, get_*, _resolve_*, _topological_sort_*

🟠 IMPORTANT (Must fix)
[ ] Each file/function has single responsibility                  ❌ native.py has 6+ responsibilities
[x] Proper error handling (no silent failures)
[x] Strong typing (no any/object types)
[x] Inputs validated at boundaries
[x] Types in dedicated types file (N/A)
[x] Constants in dedicated constants file (LANGFLOW_SPAN_NAMESPACE and TYPE_MAP could be extracted)

🟡 RECOMMENDED (Should fix)
[x] Appropriate logging at key points
[x] No unnecessary comments
[x] No over-engineering

🟢 NICE TO HAVE (Polish)
[x] Unit tests for core logic
[ ] Tests cover success, error, and edge cases                    ⚠️ Missing _resolve_span_uuids tests
[x] Not prolonging legacy bad patterns

---

All Issues Summary

#	Severity	Description	File	Action Required
1	🔴 CRITICAL	File exceeds 300 lines (633 lines)	native.py	Split by responsibility into separate files
2	🔴 CRITICAL	13+ functions with 6+ different responsibility categories	native.py	Extract to separate files per category
3	🔴 CRITICAL	Mixed function prefixes in same file	native.py	Follows from fix #1/#2
4	🟠 IMPORTANT	In-place mutation of span_data["parent_span_id"] in cycle handling	_topological_sort_spans	Create a copy instead of mutating original
5	🟠 IMPORTANT	Redundant from uuid import UUID as UUID_ inside method	_resolve_span_uuids	Use the top-level UUID import
6	🟢 TESTING	Patch path lfx.services.deps.session_scope may not work	test_flush_inserts_parent_before_child	Patch at langflow.services.tracing.native.session_scope
7	🟢 TESTING	No isolated test for _resolve_span_uuids	test_native_tracer.py	Add tests for string parent IDs, invalid UUIDs

[Cristhianzl]

lgtm