..
 # Copyright (c) 2026, Arm Limited.
 #
 # SPDX-License-Identifier: MIT

###########################
Resultstore Error Display
###########################

Implemented by ``fastpath error show``; no schema changes required.

Command
=======

Add ``fastpath error show [<resultstore>]`` to display one record per row in
the ``ERROR`` table. Follow ``result show`` for filtering and ``result list``
for the per-record layout. Support CSV, SQLite and MySQL, with the same
``default.resultstore`` preference. Errors must be visible even when a failed
benchmark produced no numerical results.

.. code-block:: shell

   fastpath error show results/ --sut lab-sut --swprofile 6-16-0-rc6
   fastpath error show results/ --type 'KMSG_*'
   fastpath error show results/ --id 42 --all --format ascii

Filters
=======

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Option
     - Selection
   * - ``--sut <id>``
     - Exact SUT identifier from ``result list``; mutually exclusive with
       ``--sutclass``.
   * - ``--sutclass <id>``
     - Exact SUT class identifier from ``result list``; selects errors from
       member SUTs.
   * - ``--swprofile <id>``
     - Exact software profile identifier from ``result list``.
   * - ``--benchmark <id>``
     - Exact benchmark identifier from ``result list``.
   * - ``--user <name>``
     - Exact user name; ``--user ''`` selects untagged errors.
   * - ``--id <id>``
     - Exact decimal error ID.
   * - ``--type <glob>``
     - Stored type, e.g. ``BENCHMARK_TIMEOUT`` or ``'KMSG_*'``.
   * - ``--session <uuid>``
     - Exact session UUID.

All comparisons are case-sensitive. Filters are repeatable: OR within a
category, AND between categories. Omitted filters include all values. Unknown
values produce an empty selection; malformed arguments produce an error.
Error IDs are local to the selected resultstore. Allow any number of SUTs and
software profiles in the output.

Retain ``--no-merge-similar`` and the existing metadata identifier rules.
Similar-object merging must never combine error records. Use the same merge
setting when discovering and selecting IDs.

Output
======

* Default ``--format pretty``: one key/value table per error containing ID,
  timestamp, type, SUT, software profile, benchmark, role and user, followed by
  the complete message. Preserve multiline text; label absent messages clearly.
* ``--all`` adds SUT class, rolemap and session UUID.
* Support ``ascii`` and ``rst`` using existing formatting conventions. Render
  stored terminal controls visibly and messages as literal text in RST.
* ``--format csv`` exports all display fields with a header and correctly quoted
  multiline messages, directly to stdout without a pager. NULLs become empty
  cells. Omit global ``--verbose`` when exporting, since it writes to stdout.
* Page human-readable output on a terminal; write redirected output directly.

Order records by newest timestamp first, breaking ties by descending numeric
ID. Preserve stored timestamps without timezone conversion.

Display all matching records and show the matching count in human-readable
output. No matches prints a short message, or only the CSV header, and exits
successfully. Displaying recorded errors also exits successfully; invalid
arguments or an unreadable/incompatible store return non-zero.