From 3ee5d0e40768fcc5b3e1d9ebe29b990754630c2d Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 22 Oct 2026 04:43:25 +0100 Subject: [PATCH] feat(app): finish the visit session export facts Split the export model/classification from the session wording, add the no-session, selected-repair and missing-evidence coverage, and update the parity matrix and R4 note. The visit probe now passes the scheme name its fixture reads, asserts the painted theme before capture and re-captures the export states. --- app/PARITY.md | 2 +- .../runs/ui/run_detail_visit_export.dart | 352 ++++++++++++++++++ .../runs/ui/run_detail_visit_recorded.dart | 31 ++ .../runs/ui/run_detail_visit_session.dart | 2 +- .../ui/run_detail_visit_session_state.dart | 344 +---------------- app/notes/R4-session-export.md | 151 ++++++++ .../run_detail_visit_session_export_test.dart | 73 ++++ app/tool/run_detail_visit_probe.dart | 64 +++- app/tool/run_detail_visit_probe.mjs | 110 +++++- 9 files changed, 794 insertions(+), 335 deletions(-) create mode 100644 app/lib/features/runs/ui/run_detail_visit_export.dart create mode 100644 app/lib/features/runs/ui/run_detail_visit_recorded.dart create mode 100644 app/notes/R4-session-export.md diff --git a/app/PARITY.md b/app/PARITY.md index bce99029..c8c667f1 100644 --- a/app/PARITY.md +++ b/app/PARITY.md @@ -39,7 +39,7 @@ or scratch servers only, never real operator sessions/runs/workflows. | Artifact groups | Preview: run detail → recorded groups, selection facts, external Open/Copy link | present the visit's turn documents (input.md/memory.md/output.md, session.html) as gallery entries; in-app viewer next | | Artifact preview | Preview: image + markdown/text in-app through the chat renderer, paging, honest unsupported/external/HTTP states | video and HTML remain external-only | | Artifact actions | Preview: external Open, Copy link, download and native share carry the recorded name/MIME bytes; progress, cancel, HTTP failure and unsupported-share states | OS share/download on Android/iOS remain unverified until the final build | -| Session audit/export repair facts | Missing UI | session.html read-only open, partial/missing/skipped/repair choices without fabricating complete evidence | +| Session audit/export repair facts | Source: the visit Session section reports the recorded export state (complete, partial, missing, skipped, repair, or the server's verbatim unknown word), its verbatim reason, and read-only repair attempt/option labels; `session.html` opens externally | published preview with fixture captures; the `repair_session_export` action and per-visit repair choices | | Chat session management | Preview list + open session; actions from the list | directory groups/search, shared rename/star/close/reopen/create, local hide/undo/seen state, create dialog in the shell | | Chat history/live transport | Preview: `/chat` list and `/chat/:id` history, paging, live failure notice | run-detail-style reconnect verification in the real app, then composer integration | | Chat message surfaces | Preview: formatted assistant markdown (safe links/headings/lists/tables/fences), user text exact, disclosures plain | exact attachments, unknown-part rendering beyond retained placeholders | diff --git a/app/lib/features/runs/ui/run_detail_visit_export.dart b/app/lib/features/runs/ui/run_detail_visit_export.dart new file mode 100644 index 00000000..7b3731a1 --- /dev/null +++ b/app/lib/features/runs/ui/run_detail_visit_export.dart @@ -0,0 +1,352 @@ +import '../../../core/api_gateway.dart'; +import '../../artifacts/domain/artifact_record.dart'; +import '../../artifacts/domain/artifact_selection.dart'; +import 'run_detail_visit_recorded.dart'; + +/// The export state the pane reports. A status this client does not know is +/// [unknown] and is shown verbatim; it is never rounded to complete. +enum VisitSessionExportState { + complete, + partial, + missing, + skipped, + repair, + unknown, +} + +/// The one state line for a visit's recorded export, with the server's own +/// diagnostic as [reason] when it recorded one. +class VisitSessionExportFact { + const VisitSessionExportFact({ + required this.state, + required this.word, + this.reason, + }); + + final VisitSessionExportState state; + + /// The state word shown to the operator. An unknown status keeps the + /// server's exact word here instead of being mapped to a known state. + final String word; + + /// The server-recorded diagnostic, verbatim, or null when there was none. + final String? reason; +} + +/// One recorded repair attempt and the read-only labels the pane shows for it. +class VisitSessionRepair { + const VisitSessionRepair({ + required this.status, + required this.messages, + this.diagnostic, + this.option, + }); + + final String status; + final int messages; + final String? diagnostic; + + /// The web pane's open label, shown read-only, or null when this repair is + /// the document the main open action already points at. + final String? option; + + /// The web audit pane's repair label, without its `Repair: ` prefix. + String get label => + '$status · $messages messages.' + '${diagnostic == null ? '' : ' $diagnostic'}'; +} + +/// A recorded session export document and the evidence the server recorded for +/// it. +class VisitSessionExport { + const VisitSessionExport({ + required this.artifact, + this.status, + this.diagnostic, + this.messages = 0, + this.htmlBytes = 0, + this.truncated = false, + this.repaired = false, + }); + + final ArtifactRecord artifact; + final String? status; + final String? diagnostic; + final int messages; + final int htmlBytes; + final bool truncated; + + /// True when the document is one of the visit's recorded repair attempts. + final bool repaired; + + /// Completeness needs the server's complete status plus positive message and + /// byte counts, an untruncated document and no diagnostic. An absent or + /// partial record is never promoted to complete. + bool get isComplete => _evidenceComplete( + status: status, + messages: messages, + htmlBytes: htmlBytes, + truncated: truncated, + diagnostic: diagnostic, + ); + + /// The evidence sentence beside a present but incomplete export, or null + /// when the export is complete or no evidence was recorded. + String? get statusNote { + if (isComplete) return null; + if (status == null && messages <= 0 && !truncated) return null; + final word = status == null || status == 'complete' ? 'partial' : status; + return 'This export is $word; full session evidence is not available.'; + } +} + +/// The recorded harness session identity, from the step or its export evidence. +String? detailVisitSessionIdentity(JsonMap step) { + final direct = recordedText(step['session_id']); + if (direct != null) return direct; + final evidence = _firstEvidence(step); + return evidence == null ? null : recordedText(evidence['session_id']); +} + +/// The visit's recorded export document, or null when no recorded export name +/// is present in the inventory. +/// +/// The step's own `session_export` is preferred; a repair document is used +/// when that is the file the inventory carries. A visit with no export evidence +/// falls back to its `session.html`, exactly as the web audit pane does. +VisitSessionExport? detailVisitSessionExport(JsonMap step) { + final evidence = _exportEvidence(step); + for (final entry in evidence) { + final artifact = recordedArtifact( + step, + recordedText(entry.evidence['html']), + ); + if (artifact == null) continue; + return VisitSessionExport( + artifact: artifact, + status: recordedText(entry.evidence['status']), + diagnostic: recordedText(entry.evidence['diagnostic']), + messages: recordedCount(entry.evidence['messages']), + htmlBytes: recordedCount(entry.evidence['html_bytes']), + truncated: entry.evidence['truncated'] == true, + repaired: entry.repaired, + ); + } + if (evidence.isNotEmpty) return null; + for (final artifact in systemArtifacts(step)) { + if (artifact.name == 'session.html') { + return VisitSessionExport(artifact: artifact); + } + } + return null; +} + +/// The recorded sentence for a visit whose export evidence names no file, in +/// the web audit pane's words: the recovery status while it is pending or +/// running, the evidence status otherwise, and the recorded diagnostic. +String missingExportMessage(JsonMap step, String sessionId) { + final evidence = _firstEvidence(step); + final recovery = step['session_export_recovery']; + final recoveryStatus = recovery is Map + ? recordedText(recovery['status']) + : null; + final evidenceStatus = evidence == null + ? null + : recordedText(evidence['status']); + final String status; + if (recoveryStatus == 'pending' || recoveryStatus == 'running') { + status = 'pending recovery'; + } else if (evidenceStatus == 'complete') { + status = 'not available in the artifact inventory'; + } else { + status = evidenceStatus ?? 'not yet available'; + } + final diagnostic = evidence == null + ? null + : recordedText(evidence['diagnostic']); + final suffix = diagnostic == null ? '' : ' $diagnostic'; + return 'Session $sessionId is recorded. Its export is $status.$suffix'; +} + +/// Every recorded repair attempt, oldest first, read-only. The open label is +/// kept only for an attempt the main open action does not already point at. +List visitSessionRepairs( + JsonMap step, + VisitSessionExport? export, +) { + final recorded = step['session_export_repairs']; + if (recorded is! List) return const []; + final selectedName = export?.artifact.name; + final repairs = []; + for (final entry in recorded) { + if (entry is! Map) continue; + final artifact = recordedArtifact(step, recordedText(entry['html'])); + final selected = artifact != null && artifact.name == selectedName; + repairs.add( + VisitSessionRepair( + status: recordedText(entry['status']) ?? 'partial', + messages: recordedCount(entry['messages']), + diagnostic: recordedText(entry['diagnostic']), + option: artifact == null || selected ? null : 'Open repaired export', + ), + ); + } + return repairs; +} + +/// The Export row for a present export document. +VisitSessionExportFact exportFactFor(VisitSessionExport export) { + if (export.repaired) { + return VisitSessionExportFact( + state: VisitSessionExportState.repair, + word: 'repair', + reason: export.diagnostic, + ); + } + final state = _exportState(export.status, evidence: export.isComplete); + if (state == VisitSessionExportState.complete) { + return const VisitSessionExportFact( + state: VisitSessionExportState.complete, + word: 'complete', + ); + } + if (state == VisitSessionExportState.partial) return _partialFact(export); + return VisitSessionExportFact( + state: VisitSessionExportState.unknown, + word: export.status ?? 'unknown', + reason: export.diagnostic, + ); +} + +/// The Export row for a visit whose evidence names no file: missing, unless the +/// evidence carries a status this client does not know, which is kept verbatim. +VisitSessionExportFact missingExportFact(JsonMap step) { + final evidence = _firstEvidence(step); + final status = evidence == null ? null : recordedText(evidence['status']); + final diagnostic = evidence == null + ? null + : recordedText(evidence['diagnostic']); + if (status != null && + _exportState(status, evidence: false) == + VisitSessionExportState.unknown) { + return VisitSessionExportFact( + state: VisitSessionExportState.unknown, + word: status, + reason: diagnostic, + ); + } + return VisitSessionExportFact( + state: VisitSessionExportState.missing, + word: 'missing', + reason: diagnostic, + ); +} + +VisitSessionExportFact _partialFact(VisitSessionExport export) => + VisitSessionExportFact( + state: VisitSessionExportState.partial, + word: 'partial', + reason: export.diagnostic, + ); + +const Set _partialStatuses = { + 'partial', + 'empty', + 'failed', + 'truncated', + 'incomplete', + 'unavailable', +}; + +/// The export state a recorded status means, with [evidence] reporting whether +/// the server's complete evidence was actually recorded for the document. +/// +/// A `complete` word without verified evidence is partial, never complete. A +/// status this client does not know, or none at all, is unknown; the caller +/// keeps the server's own word in the row. +VisitSessionExportState _exportState(String? status, {required bool evidence}) { + if (status == 'complete') { + return evidence + ? VisitSessionExportState.complete + : VisitSessionExportState.partial; + } + if (status != null && _partialStatuses.contains(status)) { + return VisitSessionExportState.partial; + } + return VisitSessionExportState.unknown; +} + +/// The one completeness rule for recorded export evidence: the server's +/// complete status, positive message and byte counts, an untruncated document +/// and no diagnostic. An incomplete record is never promoted to complete. +bool _evidenceComplete({ + required String? status, + required int messages, + required int htmlBytes, + required bool truncated, + required String? diagnostic, +}) => + status == 'complete' && + messages > 0 && + htmlBytes > 0 && + !truncated && + diagnostic == null; + +/// The recorded export evidence, most current first: a complete repair, then a +/// complete original, then every remaining candidate. A failed later attempt +/// never hides an earlier verified document; an older original never hides the +/// repair that replaced it. +List<_RecordedExport> _exportEvidence(JsonMap step) { + final repairs = []; + final recordedRepairs = step['session_export_repairs']; + if (recordedRepairs is List) { + for (final entry in recordedRepairs.reversed) { + if (entry is Map) repairs.add(entry); + } + } + final original = step['session_export']; + final ordered = <_RecordedExport>[]; + void add(Map entry, bool repaired) { + for (final candidate in ordered) { + if (identical(candidate.evidence, entry)) return; + } + ordered.add(_RecordedExport(entry, repaired)); + } + + for (final repair in repairs) { + if (_isComplete(repair)) add(repair, true); + } + if (original is Map && _isComplete(original)) add(original, false); + for (final repair in repairs) { + add(repair, true); + } + if (original is Map) add(original, false); + return ordered; +} + +class _RecordedExport { + const _RecordedExport(this.evidence, this.repaired); + + final Map evidence; + final bool repaired; +} + +Map? _firstEvidence(JsonMap step) { + final original = step['session_export']; + if (original is Map) return original; + final repairs = step['session_export_repairs']; + if (repairs is List) { + for (final entry in repairs.reversed) { + if (entry is Map) return entry; + } + } + return null; +} + +bool _isComplete(Map evidence) => _evidenceComplete( + status: recordedText(evidence['status']), + messages: recordedCount(evidence['messages']), + htmlBytes: recordedCount(evidence['html_bytes']), + truncated: evidence['truncated'] == true, + diagnostic: recordedText(evidence['diagnostic']), +); diff --git a/app/lib/features/runs/ui/run_detail_visit_recorded.dart b/app/lib/features/runs/ui/run_detail_visit_recorded.dart new file mode 100644 index 00000000..eba5e087 --- /dev/null +++ b/app/lib/features/runs/ui/run_detail_visit_recorded.dart @@ -0,0 +1,31 @@ +import '../../../core/api_gateway.dart'; +import '../../artifacts/domain/artifact_record.dart'; +import '../../artifacts/domain/artifact_selection.dart'; + +/// Reading one visit's recorded fields, shared by the session pointer and its +/// export evidence so both interpret the same reply the same way. + +/// The trimmed, non-empty text of a recorded value, or null when the reply +/// carried none. A blank string is absence, never a value. +String? recordedText(dynamic value) { + if (value == null) return null; + final text = '$value'.trim(); + return text.isEmpty ? null : text; +} + +/// A recorded count from a number or numeric string; 0 when the reply carried +/// none or something unparsable. +int recordedCount(dynamic value) { + if (value is num) return value.toInt(); + return int.tryParse('${value ?? ''}'.trim()) ?? 0; +} + +/// The inventory artifact with exactly [name], or null when [name] is absent or +/// the visit's recorded inventory carries no such file. +ArtifactRecord? recordedArtifact(JsonMap step, String? name) { + if (name == null) return null; + for (final artifact in artifactsOf(step)) { + if (artifact.name == name) return artifact; + } + return null; +} diff --git a/app/lib/features/runs/ui/run_detail_visit_session.dart b/app/lib/features/runs/ui/run_detail_visit_session.dart index 23dcccd1..838feaec 100644 --- a/app/lib/features/runs/ui/run_detail_visit_session.dart +++ b/app/lib/features/runs/ui/run_detail_visit_session.dart @@ -74,7 +74,7 @@ class _RunVisitSessionState extends State { _SessionFact( key: const Key('run-visit-session-export-reason'), label: 'Reason', - value: fact!.reason!, + value: fact.reason!, ), if (export != null && note != null) Text(note), ..._repairFacts(session.repairs), diff --git a/app/lib/features/runs/ui/run_detail_visit_session_state.dart b/app/lib/features/runs/ui/run_detail_visit_session_state.dart index b902d785..940d6a4b 100644 --- a/app/lib/features/runs/ui/run_detail_visit_session_state.dart +++ b/app/lib/features/runs/ui/run_detail_visit_session_state.dart @@ -1,6 +1,8 @@ import '../../../core/api_gateway.dart'; -import '../../artifacts/domain/artifact_record.dart'; -import '../../artifacts/domain/artifact_selection.dart'; +import 'run_detail_visit_export.dart'; +import 'run_detail_visit_recorded.dart'; + +export 'run_detail_visit_export.dart'; /// The exact wording for a visit that never started a harness session, in the /// web audit pane's order: skipped, stopped, being created, failed, and a model @@ -20,102 +22,6 @@ const String visitSessionNone = 'This visit has no harness session.'; const String visitSessionEndpointMissing = 'Set the server URL in Settings to open the session.'; -/// The export state the pane reports. A status this client does not know is -/// [unknown] and is shown verbatim; it is never rounded to complete. -enum VisitSessionExportState { - complete, - partial, - missing, - skipped, - repair, - unknown, -} - -/// The one state line for a visit's recorded export, with the server's own -/// diagnostic as [reason] when it recorded one. -class VisitSessionExportFact { - const VisitSessionExportFact({ - required this.state, - required this.word, - this.reason, - }); - - final VisitSessionExportState state; - - /// The state word shown to the operator. An unknown status keeps the - /// server's exact word here instead of being mapped to a known state. - final String word; - - /// The server-recorded diagnostic, verbatim, or null when there was none. - final String? reason; -} - -/// One recorded repair attempt and the read-only labels the pane shows for it. -class VisitSessionRepair { - const VisitSessionRepair({ - required this.status, - required this.messages, - this.diagnostic, - this.option, - }); - - final String status; - final int messages; - final String? diagnostic; - - /// The web pane's open label, shown read-only, or null when this repair is - /// the document the main open action already points at. - final String? option; - - /// The web audit pane's repair label, without its `Repair: ` prefix. - String get label => - '$status · $messages messages.' - '${diagnostic == null ? '' : ' $diagnostic'}'; -} - -/// A recorded session export document and the evidence the server recorded for -/// it. -class VisitSessionExport { - const VisitSessionExport({ - required this.artifact, - this.status, - this.diagnostic, - this.messages = 0, - this.htmlBytes = 0, - this.truncated = false, - this.repaired = false, - }); - - final ArtifactRecord artifact; - final String? status; - final String? diagnostic; - final int messages; - final int htmlBytes; - final bool truncated; - - /// True when the document is one of the visit's recorded repair attempts. - final bool repaired; - - /// Completeness needs the server's complete status plus positive message and - /// byte counts, an untruncated document and no diagnostic. An absent or - /// partial record is never promoted to complete. - bool get isComplete => - status == 'complete' && - messages > 0 && - htmlBytes > 0 && - !truncated && - diagnostic == null; - - /// The evidence sentence beside a present but incomplete export, or null - /// when the export is complete or no evidence was recorded. - String? get statusNote { - if (isComplete) return null; - if (status == null && messages <= 0 && !truncated) return null; - final word = status == null || status == 'complete' ? 'partial' : status; - return 'This export is $word; full session evidence is not available.'; - } -} - /// A visit's recorded session: identity, openable export, recorded export /// state, recorded repairs and, without a document, the recorded sentence. class VisitSessionState { @@ -149,20 +55,20 @@ class VisitSessionState { VisitSessionState detailVisitSession(JsonMap step) { final sessionId = detailVisitSessionIdentity(step); final export = detailVisitSessionExport(step); - final repairs = _repairs(step, export); + final repairs = visitSessionRepairs(step, export); if (export != null) { return VisitSessionState( sessionId: sessionId, export: export, - exportFact: _exportFact(export), + exportFact: exportFactFor(export), repairs: repairs, ); } if (sessionId != null) { return VisitSessionState( sessionId: sessionId, - message: _missingExportMessage(step, sessionId), - exportFact: _missingFact(step), + message: missingExportMessage(step, sessionId), + exportFact: missingExportFact(step), repairs: repairs, ); } @@ -178,246 +84,26 @@ VisitSessionState detailVisitSession(JsonMap step) { ); } -/// The recorded harness session identity, from the step or its export evidence. -String? detailVisitSessionIdentity(JsonMap step) { - final direct = _text(step['session_id']); - if (direct != null) return direct; - final evidence = _firstEvidence(step); - return evidence == null ? null : _text(evidence['session_id']); -} - -/// The visit's recorded export document, or null when no recorded export name -/// is present in the inventory. -/// -/// The step's own `session_export` is preferred; a repair document is used -/// when that is the file the inventory carries. A visit with no export evidence -/// falls back to its `session.html`, exactly as the web audit pane does. -VisitSessionExport? detailVisitSessionExport(JsonMap step) { - final evidence = _exportEvidence(step); - for (final entry in evidence) { - final artifact = _artifactNamed(step, _text(entry.evidence['html'])); - if (artifact == null) continue; - return VisitSessionExport( - artifact: artifact, - status: _text(entry.evidence['status']), - diagnostic: _text(entry.evidence['diagnostic']), - messages: _count(entry.evidence['messages']), - htmlBytes: _count(entry.evidence['html_bytes']), - truncated: entry.evidence['truncated'] == true, - repaired: entry.repaired, - ); - } - if (evidence.isNotEmpty) return null; - for (final artifact in systemArtifacts(step)) { - if (artifact.name == 'session.html') { - return VisitSessionExport(artifact: artifact); - } - } - return null; -} - -VisitSessionExportFact _exportFact(VisitSessionExport export) { - if (export.repaired) { - return VisitSessionExportFact( - state: VisitSessionExportState.repair, - word: 'repair', - reason: export.diagnostic, - ); - } - final status = export.status; - if (status == 'complete') { - if (export.isComplete) { - return const VisitSessionExportFact( - state: VisitSessionExportState.complete, - word: 'complete', - ); - } - return _partialFact(export); - } - if (status == null) { - return VisitSessionExportFact( - state: VisitSessionExportState.unknown, - word: 'unknown', - reason: export.diagnostic, - ); - } - if (_partialStatuses.contains(status)) return _partialFact(export); - return VisitSessionExportFact( - state: VisitSessionExportState.unknown, - word: status, - reason: export.diagnostic, - ); -} - -VisitSessionExportFact _partialFact(VisitSessionExport export) => - VisitSessionExportFact( - state: VisitSessionExportState.partial, - word: 'partial', - reason: export.diagnostic, - ); - -VisitSessionExportFact _missingFact(JsonMap step) { - final evidence = _firstEvidence(step); - final status = evidence == null ? null : _text(evidence['status']); - final diagnostic = evidence == null ? null : _text(evidence['diagnostic']); - if (status != null && - status != 'complete' && - !_partialStatuses.contains(status)) { - return VisitSessionExportFact( - state: VisitSessionExportState.unknown, - word: status, - reason: diagnostic, - ); - } - return VisitSessionExportFact( - state: VisitSessionExportState.missing, - word: 'missing', - reason: diagnostic, - ); -} - -const Set _partialStatuses = { - 'partial', - 'empty', - 'failed', - 'truncated', - 'incomplete', - 'unavailable', -}; - -List _repairs(JsonMap step, VisitSessionExport? export) { - final recorded = step['session_export_repairs']; - if (recorded is! List) return const []; - final selectedName = export?.artifact.name; - final repairs = []; - for (final entry in recorded) { - if (entry is! Map) continue; - final artifact = _artifactNamed(step, _text(entry['html'])); - final selected = artifact != null && artifact.name == selectedName; - repairs.add( - VisitSessionRepair( - status: _text(entry['status']) ?? 'partial', - messages: _count(entry['messages']), - diagnostic: _text(entry['diagnostic']), - option: artifact == null || selected ? null : 'Open repaired export', - ), - ); - } - return repairs; -} - bool _isSkipped(JsonMap step) => - _text(step['status']) == 'skipped' || _text(step['outcome']) == 'skipped'; - -String _missingExportMessage(JsonMap step, String sessionId) { - final evidence = _firstEvidence(step); - final recovery = step['session_export_recovery']; - final recoveryStatus = recovery is Map ? _text(recovery['status']) : null; - final evidenceStatus = evidence == null ? null : _text(evidence['status']); - final String status; - if (recoveryStatus == 'pending' || recoveryStatus == 'running') { - status = 'pending recovery'; - } else if (evidenceStatus == 'complete') { - status = 'not available in the artifact inventory'; - } else { - status = evidenceStatus ?? 'not yet available'; - } - final diagnostic = evidence == null ? null : _text(evidence['diagnostic']); - final suffix = diagnostic == null ? '' : ' $diagnostic'; - return 'Session $sessionId is recorded. Its export is $status.$suffix'; -} + recordedText(step['status']) == 'skipped' || + recordedText(step['outcome']) == 'skipped'; String _noSessionMessage(JsonMap step) { - final status = _text(step['status']); + final status = recordedText(step['status']); if (_isSkipped(step)) return visitSessionSkipped; if (status == 'canceled' || status == 'interrupted') { return visitSessionStopped; } - final model = _text(step['provider']) != null || _text(step['model']) != null; + final model = + recordedText(step['provider']) != null || + recordedText(step['model']) != null; if (!model) return visitSessionNone; if (status == 'running') return visitSessionStarting; if (status == 'failed') { - final diagnostic = _text(step['diagnostic']); + final diagnostic = recordedText(step['diagnostic']); return diagnostic == null ? visitSessionFailed : '$visitSessionFailed $diagnostic'; } return visitSessionNoIdentity; } - -/// The recorded export evidence, most current first: a complete repair, then a -/// complete original, then every remaining candidate. A failed later attempt -/// never hides an earlier verified document; an older original never hides the -/// repair that replaced it. -List<_RecordedExport> _exportEvidence(JsonMap step) { - final repairs = []; - final recordedRepairs = step['session_export_repairs']; - if (recordedRepairs is List) { - for (final entry in recordedRepairs.reversed) { - if (entry is Map) repairs.add(entry); - } - } - final original = step['session_export']; - final ordered = <_RecordedExport>[]; - void add(Map entry, bool repaired) { - for (final candidate in ordered) { - if (identical(candidate.evidence, entry)) return; - } - ordered.add(_RecordedExport(entry, repaired)); - } - - for (final repair in repairs) { - if (_isComplete(repair)) add(repair, true); - } - if (original is Map && _isComplete(original)) add(original, false); - for (final repair in repairs) { - add(repair, true); - } - if (original is Map) add(original, false); - return ordered; -} - -class _RecordedExport { - const _RecordedExport(this.evidence, this.repaired); - - final Map evidence; - final bool repaired; -} - -Map? _firstEvidence(JsonMap step) { - final original = step['session_export']; - if (original is Map) return original; - final repairs = step['session_export_repairs']; - if (repairs is List) { - for (final entry in repairs.reversed) { - if (entry is Map) return entry; - } - } - return null; -} - -bool _isComplete(Map evidence) => - _text(evidence['status']) == 'complete' && - _count(evidence['messages']) > 0 && - _count(evidence['html_bytes']) > 0 && - evidence['truncated'] != true && - _text(evidence['diagnostic']) == null; - -int _count(dynamic value) { - if (value is num) return value.toInt(); - return int.tryParse('${value ?? ''}'.trim()) ?? 0; -} - -ArtifactRecord? _artifactNamed(JsonMap step, String? name) { - if (name == null) return null; - for (final artifact in artifactsOf(step)) { - if (artifact.name == name) return artifact; - } - return null; -} - -String? _text(dynamic value) { - if (value == null) return null; - final text = '$value'.trim(); - return text.isEmpty ? null : text; -} diff --git a/app/notes/R4-session-export.md b/app/notes/R4-session-export.md new file mode 100644 index 00000000..c0389e27 --- /dev/null +++ b/app/notes/R4-session-export.md @@ -0,0 +1,151 @@ +# R4 — visit Session export state + +## Delivered + +The Timeline visit pane's **Session** section reports the recorded export state +as native fact rows: + +- **Export** — `complete`, `partial`, `missing`, `skipped`, `repair`, or the + server's exact unrecognised status word. +- **Reason** — the server-recorded diagnostic, verbatim, for a present export + that is not a repair; a missing export keeps its diagnostic in the recorded + sentence. +- **Repair / Repair option** — every recorded repair attempt in server order, + labelled ` · messages.< diagnostic>`, with `Open repaired export` + where a non-selected attempt has a file. These are plain text: no control and + no request. +- The existing partial-export sentence and the single `Open ` action are + unchanged. + +Completeness is not inferred: it requires `status == "complete"`, positive +`messages` and `html_bytes`, no truncation and no diagnostic. A complete status +without that evidence is `partial`; a legacy `session.html` with no evidence is +`unknown`, never `complete`. Repairs are shown even when the main export is +complete. No `repair_session_export` request is sent or advertised. + +## Review fixes (visit 2) + +- Removed the analyzer-gate warning at + `lib/features/runs/ui/run_detail_visit_session.dart:77` + (`unnecessary_non_null_assertion`); `flutter analyze` is clean again. +- One completeness rule: `_evidenceComplete` now backs both + `VisitSessionExport.isComplete` and the evidence-selection check, so selection + and display cannot drift. +- One status classifier: `_exportState` backs both the present-export and + missing-file fact rows. `complete` without evidence is partial, known partial + statuses are partial, anything else is unknown with the server's own word. +- Split the 449-line session state file by responsibility: session wording and + state assembly (`run_detail_visit_session_state.dart`, 109 lines), export + model/resolution/classification (`run_detail_visit_export.dart`, 352 lines), + and shared recorded-field reading (`run_detail_visit_recorded.dart`, 31 + lines). The state file re-exports the export file, so the pane and existing + tests keep one import. +- Added the three coverage gaps the review named: a non-skipped visit with no + session has no Export row; a selected repair suppresses the Reason row; an + evidence status whose named file is missing keeps the server word and puts + the diagnostic in the recorded sentence. +- Extended the existing real-browser visit probe with a complete-export visit + that carries a failed repair, and a partial-export visit with a diagnostic. +- Updated `PARITY.md` so the row no longer says "Missing UI". + +## Theme render fix (visit 3) + +The UI review found that `PROBE_SCHEME=dark` never painted dark: the driver sent +`theme=1`, while the fixture compares `params['theme'] == 'dark'`. Every earlier +`-dark-` capture was therefore light. Fixed in +`tool/run_detail_visit_probe.mjs`: the driver now passes the scheme name, and the +probe samples the painted page (mean luminance over the screenshot) before any +capture. A dark run must paint below 0.5 mean luminance and a light run above it, +so this mismatch fails loudly instead of silently labelling light captures dark. +A negative check with the old `theme=1` URL fails with +`PROBE_SCHEME=dark painted the other theme (mean luminance 0.970)`. + +All four dark combinations were re-run and all their captures regenerated: +Material/Cupertino × 1280×900/1× and 320×568/2×. Measured mean luminance is +0.084 (Material 1280), 0.140 (Material 320), 0.081 (Cupertino 1280) and 0.116 +(Cupertino 320). No test, check or page exception occurred. + +## Files + +Changed: + +- `app/lib/features/runs/ui/run_detail_visit_session.dart` — one-line analyzer + fix; rendering unchanged. +- `app/lib/features/runs/ui/run_detail_visit_session_state.dart` — now session + wording/state assembly plus a re-export of the export module. +- `app/test/features/runs/ui/run_detail_visit_session_export_test.dart` — 11 + tests (8 delivered + 3 review gaps). +- `app/tool/run_detail_visit_probe.dart` — two server-shaped export-state visits. +- `app/tool/run_detail_visit_probe.mjs` — export-row checks, narrow-layout + scrolling, two new captures per host/size, corrected scheme query parameter and + a painted-theme luminance gate. +- `app/PARITY.md` — session audit/export row updated to Source with the + remaining action/publication named. + +Added: + +- `app/lib/features/runs/ui/run_detail_visit_export.dart` — export state enum, + fact/repair/export models, evidence ordering, status classification, + completeness rule. +- `app/lib/features/runs/ui/run_detail_visit_recorded.dart` — recorded text, + count and artifact lookup shared by both modules. +- `app/notes/R4-session-export.md` — this note. + +## Checks run + +From `app/`, Flutter 3.44.6: + +| Command | Result | +| --- | --- | +| `flutter analyze` | **No issues found** (was 1 warning, exit 1) | +| `dart format --output=none --set-exit-if-changed` on the 6 changed Dart files | 0 changed, exit 0 | +| `flutter test test/features/runs/ui` | 142 passed | +| `flutter test test/features/runs` | **205 passed** | +| `flutter test` | **1247 passed** | +| `flutter build web` | `Built build/web`, exit 0 | +| `flutter build web --target tool/run_detail_visit_probe.dart --output build/probe-run-detail-visit` | built, exit 0 | +| `node tool/run_detail_visit_probe.mjs` × 4 host/size combos | 12/12 checks true in each (includes the painted-theme check) | + +## Browser evidence + +The real `RunDetailView` was driven over the probe's fake `get_run` gateway with +a fourth and fifth recorded visit. The checks assert, for the audit visit, +`Export complete`, `Repair failed · 0 messages. The repair read failed.`, +`Repair option Open repaired export`, `Open session.html`, and no Reason row; +for the partial visit, `Export partial`, `Reason The native read was refused.` +and the sentence `This export is failed; full session evidence is not +available.` The existing pane/session/gallery checks still pass. + +Under `/Users/alan/.local/share/pipelines/data/artifacts/110/public/r4-session-export/`: + +| Host | Viewport | New captures | +| --- | --- | --- | +| Material | 1280×900, dark, 1x | `run-detail-visit-material-dark-1x-1280x900-{export-complete-repair,export-partial-reason}.png` | +| Material | 320×568, dark, 2x | `run-detail-visit-material-dark-2x-320x568-{export-complete-repair,export-partial-reason}.png` | +| Cupertino | 1280×900, dark, 1x | `run-detail-visit-cupertino-dark-1x-1280x900-{export-complete-repair,export-partial-reason}.png` | +| Cupertino | 320×568, dark, 2x | `run-detail-visit-cupertino-dark-2x-320x568-{export-complete-repair,export-partial-reason}.png` | + +Each combo also re-captures the 8 existing states (40 PNGs total). Evidence +JSON: `evidence-{material,cupertino}-{1x-1280x900,2x-320x568}.json`, 12 true +checks each, including the measured page luminance. + +The 1280×900 captures show every row on one screen in true dark. At 320×568 with +2x text the pre-existing 240px minimum tab body leaves a short scroll region: the +probe scrolls to reach and verify the rows (no overflow or exception), and the 2x +captures show the header plus the start of the facts rather than the whole +section. The rows are present and reachable, but the 320 capture is not proof of +legibility at rest; the UI review's scrolled captures cover that. This is the same +narrow-layout constraint recorded in `notes/R4-visit.md`, not new to this change. + +## Not verified / preserved + +- Web only. Android/iOS builds and device rendering were not run; the source + remains portable (Material/Cupertino theme roles and plain text layout only). +- No authenticated server or production run was touched; fixtures only. The + preview is not published to 8096. +- `repair_session_export` remains unwired, and the repair-option label remains + inert text by design. +- Artifact matching still selects by recorded name only, as it did before this + change; web additionally filters repairs by session/backend/directory and + checks `size_bytes == html_bytes`. Inherited, not changed here. +- No commit, push, merge or deployment. diff --git a/app/test/features/runs/ui/run_detail_visit_session_export_test.dart b/app/test/features/runs/ui/run_detail_visit_session_export_test.dart index 866c0c73..5aded8ec 100644 --- a/app/test/features/runs/ui/run_detail_visit_session_export_test.dart +++ b/app/test/features/runs/ui/run_detail_visit_session_export_test.dart @@ -169,6 +169,79 @@ void main() { expect(find.text('Open session-repair-2.html'), findsOneWidget); }); + testWidgets('a visit with no session shows no export row', (tester) async { + final step = sessionStep() + ..remove('session_id') + ..remove('session_export') + ..remove('artifacts') + ..remove('provider') + ..remove('model'); + await pumpSessionExport(tester, step); + + expect(find.byKey(const Key('run-visit-session-export')), findsNothing); + expect( + find.byKey(const Key('run-visit-session-export-reason')), + findsNothing, + ); + expect(find.text(visitSessionNone), findsOneWidget); + }); + + testWidgets('a selected repair keeps its diagnostic off the Reason row', ( + tester, + ) async { + final step = sessionStep()..remove('session_export'); + step['session_export_repairs'] = [ + { + 'html': 'session-repair-1.html', + 'status': 'failed', + 'messages': 0, + 'diagnostic': 'The repair read failed.', + }, + ]; + step['artifacts'] = [artifact('session-repair-1.html')]; + await pumpSessionExport(tester, step); + + expect(find.text('repair'), findsOneWidget); + expect( + find.byKey(const Key('run-visit-session-export-reason')), + findsNothing, + ); + expect( + find.text('failed · 0 messages. The repair read failed.'), + findsOneWidget, + ); + expect(find.text('Open session-repair-1.html'), findsOneWidget); + }); + + testWidgets('evidence whose named file is missing keeps its word', ( + tester, + ) async { + final step = sessionStep(); + step['session_export'] = { + 'html': 'session.html', + 'status': 'quarantined', + 'diagnostic': 'The server quarantined this export.', + }; + step['artifacts'] = [artifact('plan.csv')]; + await pumpSessionExport(tester, step); + + expect(find.text('quarantined'), findsOneWidget); + expect(find.text('missing'), findsNothing); + // The document is absent, so the diagnostic stays in the recorded + // sentence rather than a Reason row. + expect( + find.byKey(const Key('run-visit-session-export-reason')), + findsNothing, + ); + expect( + find.textContaining( + 'Its export is quarantined. The server quarantined this export.', + ), + findsOneWidget, + ); + expect(find.textContaining('Open '), findsNothing); + }); + testWidgets('an unrecognised export status is kept verbatim', (tester) async { final step = sessionStep(); step['session_export'] = { diff --git a/app/tool/run_detail_visit_probe.dart b/app/tool/run_detail_visit_probe.dart index 53750471..9eb0c91d 100644 --- a/app/tool/run_detail_visit_probe.dart +++ b/app/tool/run_detail_visit_probe.dart @@ -30,7 +30,9 @@ class _FakeGateway implements ApiGateway { } } -/// plan -> build, with a rich first visit and a sparse second visit. +/// plan -> build, with a rich first visit, a sparse second visit, a third visit +/// whose complete export carries a recorded failed repair, and a fourth whose +/// export is partial with a diagnostic. JsonMap _graph() => { 'name': 'Release verification', 'stages': [ @@ -109,6 +111,66 @@ JsonMap _run() => { 'target': '#success', 'diagnostic': 'Built.', }, + { + 'stage': 'audit', + 'sequence': 3, + 'status': 'completed', + 'outcome': 'success', + 'target': '#success', + 'diagnostic': 'Audited.', + 'session_id': 'sess-2', + 'session_export': { + 'html': 'session.html', + 'status': 'complete', + 'messages': 3, + 'html_bytes': 500, + }, + 'session_export_repairs': [ + { + 'html': 'session-repair-1.html', + 'status': 'failed', + 'messages': 0, + 'diagnostic': 'The repair read failed.', + }, + ], + 'artifacts': [ + { + 'name': 'session.html', + 'url': 'https://example.test/artifacts/session.html', + 'content_type': 'text/html', + 'size_bytes': 100, + }, + { + 'name': 'session-repair-1.html', + 'url': 'https://example.test/artifacts/session-repair-1.html', + 'content_type': 'text/html', + 'size_bytes': 100, + }, + ], + }, + { + 'stage': 'partial', + 'sequence': 4, + 'status': 'completed', + 'outcome': 'success', + 'target': '#success', + 'diagnostic': 'Partial export recorded.', + 'session_id': 'sess-3', + 'session_export': { + 'html': 'session.html', + 'status': 'failed', + 'messages': 2, + 'diagnostic': 'The native read was refused.', + }, + 'artifacts': [ + { + 'name': 'session.html', + 'url': 'https://example.test/artifacts/session.html', + 'content_type': 'text/html', + 'size_bytes': 100, + }, + ], + }, ], }; diff --git a/app/tool/run_detail_visit_probe.mjs b/app/tool/run_detail_visit_probe.mjs index 5e540d81..35cbf32a 100644 --- a/app/tool/run_detail_visit_probe.mjs +++ b/app/tool/run_detail_visit_probe.mjs @@ -7,8 +7,12 @@ // recorded Input, Artifacts, Session and Definition, that the visit's artifact // row opens a gallery listing exactly that visit's attributed files, that Back // returns to the rows, that a sparse visit does not invent Duration or -// provider/model, and that a visit with no artifact field says the capture is -// unavailable rather than empty. +// provider/model, that a visit with no artifact field says the capture is +// unavailable rather than empty, and that the Session section renders the +// recorded export state: a complete export with a read-only failed repair and +// its open option, and a partial export with its state word and recorded +// reason. It also samples the rendered page so PROBE_SCHEME=dark cannot pass +// while the fixture silently renders light. // // PROBE_VARIANT=material|cupertino PROBE_SCHEME=dark|light PROBE_SCALE=1|2 \ // PROBE_WIDTH=1280 PROBE_HEIGHT=900 PROBE_WEB_ROOT= \ @@ -175,6 +179,23 @@ try { }; const clickLabel = (label, options) => clickSemantics(label, options); const clickPrefix = (prefixText) => clickSemantics(prefixText, { prefix: true }); + const scrollPage = async (deltaY) => { + await send('Input.dispatchMouseEvent', { + type: 'mouseWheel', x: width / 2, y: height - 24, deltaX: 0, deltaY, + }, session); + await delay(700); + }; + // A short tab body at 320/2x builds its rows lazily: scroll toward the row + // before requiring it, and leave the page there so the capture follows the + // facts. Semantics can include clipped rows, so the 320 capture proves the + // rows are in the tree; legibility at rest is checked by the UI review. + const ensureText = async (needle, context) => { + for (let attempt = 0; attempt < 8; attempt++) { + if ((await bodyText()).includes(needle)) return; + await scrollPage(240); + } + throw new Error(`${context}: missing ${JSON.stringify(needle)}\n${await bodyText()}`); + }; const capture = async (name) => { const data = (await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false, @@ -183,11 +204,41 @@ try { await writeFile(join(artifactDir, file), Buffer.from(data, 'base64')); return file; }; + // Mean luminance of the actual render. The fixture receives the scheme through + // its own query parameter, so a mismatch between PROBE_SCHEME and the painted + // theme (as happened when the driver sent theme=1 and the fixture read + // 'dark') must fail rather than label a light capture as dark. + const pageLuminance = async () => { + const shot = (await send('Page.captureScreenshot', { + format: 'png', captureBeyondViewport: false, + }, session)).result.data; + return evaluate(`(async () => { + const img = new Image(); + img.src = 'data:image/png;base64,${shot}'; + await img.decode(); + const canvas = document.createElement('canvas'); + canvas.width = img.width; + canvas.height = img.height; + const ctx = canvas.getContext('2d'); + ctx.drawImage(img, 0, 0); + const data = ctx.getImageData(0, 0, img.width, img.height).data; + let sum = 0; + let samples = 0; + for (let y = 0; y < img.height; y += 8) { + for (let x = 0; x < img.width; x += 8) { + const i = (y * img.width + x) * 4; + sum += (0.2126 * data[i] + 0.7152 * data[i + 1] + 0.0722 * data[i + 2]) / 255; + samples += 1; + } + } + return { mean: sum / samples, samples }; + })()`); + }; const evidence = { variant, scheme, scale, width, height, checks: [], captures: [] }; const check = (text, value) => evidence.checks.push({ check: text, value }); const navigation = await send('Page.navigate', { - url: `http://127.0.0.1:${port}/?platform=${variant}&theme=${scheme === 'dark' ? 1 : 0}&scale=${scale}`, + url: `http://127.0.0.1:${port}/?platform=${variant}&theme=${scheme}&scale=${scale}`, }, session); if (navigation.error || navigation.result?.errorText) throw new Error(JSON.stringify(navigation)); await delay(3200); @@ -196,6 +247,17 @@ try { await waitForText('Release verification', 'fixture load'); check('the real run detail opened over the recorded fixture', true); + const render = await pageLuminance(); + evidence.pageLuminance = render.mean; + evidence.pageLuminanceSamples = render.samples; + const renderedDark = render.mean < 0.5; + if (renderedDark !== (scheme === 'dark')) { + throw new Error( + `PROBE_SCHEME=${scheme} painted the other theme (mean luminance ${render.mean.toFixed(3)})`, + ); + } + check(`the ${scheme} scheme actually renders ${scheme === 'dark' ? 'dark' : 'light'}`, true); + await clickLabel('Graph'); await waitForText('Executed', 'graph legend'); await clickPrefix('plan'); @@ -256,6 +318,48 @@ try { check('a visit without an artifact field says capture unavailable', true); evidence.captures.push(await capture('sparse-artifacts')); + await clickLabel('Back to timeline'); + await waitForText('plan · visit 1', 'rows before the export-state checks'); + await clickPrefix('audit · visit 3'); + await waitForText('audit · visit 3', 'recorded export visit'); + await clickLabel('Session', { lowest: true }); + await ensureText('Open repaired export', 'recorded repair option'); + await ensureText( + 'failed · 0 messages. The repair read failed.', + 'recorded repair label', + ); + await ensureText('Open session.html', 'recorded export open'); + const auditText = await bodyText(); + if (!auditText.includes('Export complete')) { + throw new Error(`The complete export state is missing\n${auditText}`); + } + if (auditText.includes('Reason')) { + throw new Error(`A complete export showed a Reason row\n${auditText}`); + } + check('a complete export shows its read-only repair attempt and option', true); + evidence.captures.push(await capture('export-complete-repair')); + + await clickLabel('Back to timeline'); + await waitForText('plan · visit 1', 'rows before the partial export check'); + await ensureText('partial · visit 4', 'partial export row'); + await clickPrefix('partial · visit 4'); + await waitForText('partial · visit 4', 'partial export visit'); + await clickLabel('Session', { lowest: true }); + await ensureText( + 'This export is failed; full session evidence is not available.', + 'partial export sentence', + ); + await ensureText('The native read was refused.', 'partial export reason'); + const partialText = await bodyText(); + if (!partialText.includes('Export partial')) { + throw new Error(`The partial export state is missing\n${partialText}`); + } + if (!partialText.includes('Reason The native read was refused.')) { + throw new Error(`The partial export reason is missing\n${partialText}`); + } + check('a partial export shows its state word and recorded reason', true); + evidence.captures.push(await capture('export-partial-reason')); + await clickLabel('Back to timeline'); await waitForText('plan · visit 1', 'rows before the gallery check'); await clickPrefix('plan · visit 1');