fix(flows): allow pending trace IDs in flow responses

[N1neSun]

Description of the Change

Problem

The database schema allows flows.trace_id to be NULL, which can occur while observability initialization is still pending. However, the server-side Flow model treated trace_id as required and declared the column as NOT NULL.

As a result, valid flow records with a pending trace ID could fail model validation when returned by endpoints such as GET /flows.

Solution

This change aligns the server model with the existing nullable database schema:

• Makes Flow.TraceID optional while retaining the 70-character maximum length validation.
• Removes the incorrect NOT NULL GORM constraint.
• Updates the generated Swagger documentation so trace_id is no longer required.
• Adds model tests covering missing and oversized trace IDs.
• Adds a service-level regression test confirming that GET /flows returns flows with pending trace IDs successfully.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• 🚀 New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔧 Configuration change
• 🧪 Test update
• 🛡️ Security update

Areas Affected

• Core Services (Frontend UI/Backend API)
• AI Agents (Researcher/Developer/Executor)
• Security Tools Integration
• Memory System (Vector Store/Knowledge Base)
• Monitoring Stack (Grafana/OpenTelemetry)
• Analytics Platform (Langfuse)
• External Integrations (LLM/Search APIs)
• Documentation
• Infrastructure/DevOps

Testing and Verification

Test Configuration

PentAGI Version: 1154a81
Docker Version: Not used
Host OS: Windows
LLM Provider: Not required
Enabled Features: []

Test Steps

1. Run the flow model validation tests:

   cd backend
   go test ./pkg/server/models -run '^TestFlowValid$' -count=1

2. Run the flow service regression test:

   go test ./pkg/server/services -run '^TestGetFlowsAllowsPendingTraceID$' -count=1

3. Run static analysis for the affected packages:

   go vet ./pkg/server/models ./pkg/server/services

Test Results

All tests and static analysis relevant to this change passed:

ok   pentagi/pkg/server/models
ok   pentagi/pkg/server/services
go vet completed successfully

The complete services test suite has unrelated Windows-specific failures involving path separators and filename handling. The new regression test passes independently.

Security Considerations

This change does not modify authentication, authorization, permissions, or sensitive-data handling.

Allowing a temporarily missing trace ID does not bypass any access controls. The existing maximum-length validation remains in place when a trace ID is provided.

Performance Impact

No measurable performance impact is expected. The change only adjusts validation and schema metadata for one optional field and does not add database queries or processing overhead.

Documentation Updates

• README.md updates
• API documentation updates
• Configuration documentation updates
• GraphQL schema updates
• Other

The generated Swagger JSON, YAML, and Go documentation have been updated to represent trace_id as optional.

Deployment Notes

No special deployment steps, environment variables, configuration changes, or database migrations are required.

The existing database migration already defines flows.trace_id as nullable.

Checklist

Code Quality

• My code follows the project's coding standards
• I have added/updated necessary documentation
• I have added tests to cover my changes
• All new and existing tests pass
• I have run go fmt and go vet (for Go code)
• I have run pnpm run lint (for TypeScript/JavaScript code)

Security

• I have considered security implications
• Changes maintain or improve the security model
• Sensitive information has been properly handled

Compatibility

• Changes are backward compatible
• Breaking changes are clearly marked and documented
• Dependencies are properly updated

Documentation

• Documentation is clear and complete
• Comments are added for non-obvious code
• API changes are documented

Additional Notes

The flows.trace_id database column was already nullable. This change corrects the server model and API schema so they accurately reflect the existing database behavior.

[asdek]

hey @N1neSun
thank you for the PR!