REL-CAT-001 — Distinguish discovery failure from an empty node
| Field | Value |
|---|---|
| Status | Open finding; source-verified |
| Severity | High |
| Affected surface | Catalog and schema expansion |
| Implementation issue | oqullus #531 |
| Code-change repository | sparqd/oqullus |
Where the problem appears
Expand a catalog or schema while its discovery dependency returns an error, then restore the dependency without reloading.
Concrete observed case
A failed child request is stored as children loaded with an empty list. The node appears genuinely empty and provides no visible error or node-level Retry.
Expected condition
Represent idle, loading, loaded-empty, failed, and stale states separately. Show a concise dependency error and Retry at the affected node without discarding known-good siblings.
Cause and evidence
- Failure handling commits an empty loaded child set.
- The rendered tree has no node-specific failure state.
- Recovery requires a broader remount or refresh rather than retrying the failed operation.
Why it matters
Users can conclude that catalogs, schemas, or tables do not exist when discovery actually failed, leading to incorrect access and data conclusions.
Existing controls and workarounds
Refresh the whole Catalog page after confirming the dependency recovered. An empty node should not be treated as authoritative while this finding is open.
Alternatives considered
- Recommended: explicit node state with scoped Retry.
- Global error banner — useful context but insufficient for identifying which branch failed.
- Automatically retry indefinitely — rejected because deterministic failures and outages need visible control.
Component involvement
- Oqullus owns tree state and recovery presentation.
- BFF supplies structured error categories and correlation identifiers.
- Operations correlates dependency failures.
Reproduction and verification
Follow CAT-S002. Record the visible state, request outcome, effective identity, and recovery behavior relevant to this finding.
Resolution conditions
Close when failed and empty are visibly distinct, Retry restores the node without full reload, stale data is labelled, and sibling state remains intact.
Validation and blockers
Oqullus is primary; BFF error semantics require validation.