[FIX]: Preserve reports with duplicate timestamps

[Rio Yu (rioyu123)]

Description

JsonFileReportSink used a seconds-precision timestamp with write_text(). Two reports emitted within the same second therefore resolved to the same path, allowing the later report to silently replace the first.

This change preserves every report while keeping the common filename concise:

• Report filenames now use a UTC timestamp with millisecond precision, for example run_report_2026-04-25T14-30-00-123.json.
• The timestamp path is created exclusively with mode x, so an existing report is never overwritten.
• A UUID suffix is added only when the timestamp path already exists; the fallback path is also created exclusively.
• Reports continue to be fully serialized before any output file is opened, so serialization failures do not leave empty report files.
• Report content is written with explicit UTF-8 encoding instead of the platform default.

The usage guide and API documentation now describe the concise common filename, collision fallback, and remaining error cases. Tests cover repeated timestamps, existing-file preservation, a forced fallback collision, and serialization failure.

Validation:

• uv run pre-commit run --all-files — passed
• uv run pytest tests/unit/reporting -q — 46 passed
• uv run pytest tests/unit -q — 1035 passed on Linux; 1033 passed and 2 skipped on Windows
• uv run --group docs mkdocs build --strict — passed on Linux

Breaking changes

There are no public API or report-schema changes. Generated filenames now include milliseconds and may include a UUID suffix on collision. Consumers using run_report_*.json are unaffected; consumers parsing the exact timestamp format should account for the additional millisecond segment.

Checklist

• pre-commit run --all-files passes
• Tests added or updated for changes
• Documentation updated

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Rio Yu (rioyu123)]

@microsoft-github-policy-service agree

[Nina Chikanov (nina-msft)]

Thanks for flagging this Rio Yu (@rioyu123)! Let me know what you think of the following comments :-)

Whoops - meant to comment only instead of approval :-)

[Nina Chikanov (nina-msft)]

Actually, could we add the UUID only when the millisecond filename collides? For example:

timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H-%M-%S-%f")[:-3]
content = json.dumps(data, indent=2, default=str)
filepath = self._output_dir / f"run_report_{timestamp}.json"

try:
    report_file = filepath.open("x", encoding="utf-8")
except FileExistsError:
    filepath = self._output_dir / f"run_report_{timestamp}_{uuid4().hex}.json"
    report_file = filepath.open("x", encoding="utf-8")

with report_file:
    report_file.write(content)

This keeps the common filename concise while preserving atomic no-overwrite behavior.

[Rio Yu (rioyu123)]

Done. The sink now opens run_report_<millisecond timestamp>.json exclusively first and appends a UUID only if that path already exists. The fallback is also opened exclusively, so the common filename stays concise and same-millisecond reports cannot overwrite each other. Tests cover both paths.

[Nina Chikanov (nina-msft)]

If we implement behavior that I commented on below, the exact filename collision will just be avoided by adding the uuid at the end and we shouldn't raise FileExistsError :-)

[Rio Yu (rioyu123)]

Agreed. The guide now shows the concise millisecond filename and explains that a same-timestamp collision is handled by appending a UUID. It no longer says that an ordinary timestamp collision raises FileExistsError.