merge(app): land run-session-audit micro-slice

This commit is contained in:
2026-10-22 09:50:21 +01:00
9 changed files with 1075 additions and 191 deletions
+1 -1
View File
@@ -39,7 +39,7 @@ or scratch servers only, never real operator sessions/runs/workflows.
| Artifact groups | Preview: recorded groups in run detail, per-visit drill-down, turn documents (input/memory/output, session.html) in the run gallery | video/HTML preview remains external-only |
| 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), the recorded reason for a present export, and read-only repair attempt/option labels; `session.html` opens externally | publish a preview of these captures; the `repair_session_export` action and per-visit repair choices |
| Chat session management | Preview list + open session; shared create/rename/star/close/reopen with server-refreshed rows and full-width row refusals; local hide/undo and this device's read watermark (open rows only; a closed row never shows `New`) | dismissible web action-failed report (refusals stay under their row until the next accepted action), web `Open` badge and active/deep-linked read suppression, live `New` marks from pushed chat events, hide closing an already-open conversation, create dialog in the shell, editable create title (the web fixes `New chat`) |
| 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 |
@@ -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<VisitSessionRepair> visitSessionRepairs(
JsonMap step,
VisitSessionExport? export,
) {
final recorded = step['session_export_repairs'];
if (recorded is! List) return const [];
final selectedName = export?.artifact.name;
final repairs = <VisitSessionRepair>[];
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<String> _partialStatuses = <String>{
'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 = <Map>[];
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']),
);
@@ -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;
}
@@ -8,12 +8,15 @@ import '../../artifacts/domain/artifact_url.dart';
import '../../artifacts/ui/artifact_external_open.dart';
import 'run_detail_visit_session_state.dart';
/// The visit's recorded session pointer and, when the visit exported one, a
/// read-only external open of that document.
/// The visit's recorded session pointer, its recorded export state and, when
/// the visit exported one, a read-only external open of that document.
///
/// The state comes from [detailVisitSession], so a legacy `session.html`, a
/// repair, a still-running session and a failed one each report what the server
/// recorded. The open goes through the landed safe-link helper: the recorded url
/// recorded. Complete, partial, missing, skipped, repair and unrecognised
/// states each keep the server's own word and diagnostic; recorded repair
/// attempts and their open-option labels are shown read-only and make no
/// request. The open goes through the landed safe-link helper: the recorded url
/// is resolved by [resolveArtifactUrl] and passed to [openArtifactExternally]
/// without being fetched, rewritten or previewed. A refusal is reported.
class RunVisitSession extends StatefulWidget {
@@ -53,17 +56,34 @@ class _RunVisitSessionState extends State<RunVisitSession> {
? null
: resolveArtifactUrl(widget.configuredEndpoint, export.artifact.url);
final note = export?.statusNote;
final fact = session.exportFact;
final showReason =
export != null &&
fact?.reason != null &&
fact!.state != VisitSessionExportState.repair;
final children = <Widget>[
if (session.sessionId != null)
_SessionFact(label: 'Session', value: session.sessionId!),
if (export != null) ...[
if (note != null) Text(note),
if (resolved == null)
const Text(visitSessionEndpointMissing)
else
_openButton(export.artifact, resolved),
] else
Text(session.message),
if (fact != null)
_SessionFact(
key: const Key('run-visit-session-export'),
label: 'Export',
value: fact.word,
),
if (showReason)
_SessionFact(
key: const Key('run-visit-session-export-reason'),
label: 'Reason',
value: fact.reason!,
),
if (export != null && note != null) Text(note),
..._repairFacts(session.repairs),
if (export == null)
Text(session.message)
else if (resolved == null)
const Text(visitSessionEndpointMissing)
else
_openButton(export.artifact, resolved),
if (_status != null)
Padding(
padding: const EdgeInsets.only(top: 8),
@@ -110,6 +130,33 @@ class _RunVisitSessionState extends State<RunVisitSession> {
);
}
/// Recorded repair attempts, in the pane's own fact rows. Nothing here is a
/// control: the repair request belongs to its own action and is not wired.
List<Widget> _repairFacts(List<VisitSessionRepair> repairs) {
final facts = <Widget>[];
for (var index = 0; index < repairs.length; index += 1) {
final repair = repairs[index];
facts.add(
_SessionFact(
key: ValueKey('run-visit-session-repair-$index'),
label: 'Repair',
value: repair.label,
),
);
final option = repair.option;
if (option != null) {
facts.add(
_SessionFact(
key: ValueKey('run-visit-session-repair-option-$index'),
label: 'Repair option',
value: option,
),
);
}
}
return facts;
}
List<Widget> _spaced(List<Widget> children) => [
for (var index = 0; index < children.length; index += 1) ...[
if (index > 0) const SizedBox(height: 8),
@@ -119,7 +166,7 @@ class _RunVisitSessionState extends State<RunVisitSession> {
}
class _SessionFact extends StatelessWidget {
const _SessionFact({required this.label, required this.value});
const _SessionFact({super.key, required this.label, required this.value});
final String label;
final String value;
@@ -1,11 +1,12 @@
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: a skipped visit, a stopped one, a model visit whose
/// session is still being created, a failed one, and a model visit with no
/// identity at all. Only a non-model visit with nothing recorded gets the
/// web audit pane's order: skipped, stopped, being created, failed, and a model
/// visit with no identity. Only a non-model visit with nothing recorded gets the
/// generic sentence.
const String visitSessionSkipped =
'This visit was skipped; no harness session was started.';
@@ -21,210 +22,88 @@ const String visitSessionNone = 'This visit has no harness session.';
const String visitSessionEndpointMissing =
'Set the server URL in Settings to open the session.';
/// 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.truncated = false,
});
final ArtifactRecord artifact;
final String? status;
final String? diagnostic;
final bool truncated;
/// A partial or failed export is still the recorded document; it stays
/// openable and the pane says what the evidence reports.
bool get isComplete => status == 'complete' && !truncated;
/// The evidence sentence shown beside a present but incomplete export, or
/// null when the export is complete or the visit recorded no evidence.
String? get statusNote {
if (isComplete) return null;
if (status == null && !truncated) return null;
return 'This export is ${status ?? 'partial'}; full session evidence is '
'not available.';
}
}
/// A visit's recorded session: its identity, an openable export document and,
/// when neither exists, the one sentence describing the recorded state.
/// A visit's recorded session: identity, openable export, recorded export
/// state, recorded repairs and, without a document, the recorded sentence.
class VisitSessionState {
const VisitSessionState({this.sessionId, this.export, this.message = ''});
const VisitSessionState({
this.sessionId,
this.export,
this.message = '',
this.exportFact,
this.repairs = const [],
});
final String? sessionId;
final VisitSessionExport? export;
/// Empty exactly when [export] is present.
final String message;
/// Null when the visit recorded no session at all.
final VisitSessionExportFact? exportFact;
/// Every recorded repair attempt, oldest first, read-only.
final List<VisitSessionRepair> repairs;
}
/// Resolves the recorded session state without inventing a session.
///
/// The export is looked up through the recorded export evidence (including a
/// repair that replaced it) and then, for a historical visit that recorded no
/// evidence at all, through the `session.html` its inventory carries. When the
/// evidence names no file, its own status and diagnostic are reported instead
/// of claiming the inventory is empty.
/// repair that replaced it) and then, for a historical visit with no evidence,
/// through its `session.html`. When the evidence names no file, its own status
/// and diagnostic are reported instead of claiming the inventory is empty.
VisitSessionState detailVisitSession(JsonMap step) {
final sessionId = detailVisitSessionIdentity(step);
final export = detailVisitSessionExport(step);
final repairs = visitSessionRepairs(step, export);
if (export != null) {
return VisitSessionState(sessionId: sessionId, export: export);
return VisitSessionState(
sessionId: sessionId,
export: export,
exportFact: exportFactFor(export),
repairs: repairs,
);
}
if (sessionId != null) {
return VisitSessionState(
sessionId: sessionId,
message: _missingExportMessage(step, sessionId),
message: missingExportMessage(step, sessionId),
exportFact: missingExportFact(step),
repairs: repairs,
);
}
return VisitSessionState(message: _noSessionMessage(step));
return VisitSessionState(
message: _noSessionMessage(step),
exportFact: _isSkipped(step)
? const VisitSessionExportFact(
state: VisitSessionExportState.skipped,
word: 'skipped',
)
: null,
repairs: repairs,
);
}
/// 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 actually carries. A visit with no export
/// evidence at all falls back to its `session.html` system artifact, exactly as
/// the web audit pane does for runs recorded before the evidence field existed.
VisitSessionExport? detailVisitSessionExport(JsonMap step) {
final evidence = _exportEvidence(step);
for (final entry in evidence) {
final artifact = _artifactNamed(step, _text(entry['html']));
if (artifact == null) continue;
return VisitSessionExport(
artifact: artifact,
status: _text(entry['status']),
diagnostic: _text(entry['diagnostic']),
truncated: entry['truncated'] == true,
);
}
if (evidence.isNotEmpty) return null;
for (final artifact in systemArtifacts(step)) {
if (artifact.name == 'session.html') {
return VisitSessionExport(artifact: artifact);
}
}
return null;
}
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';
}
bool _isSkipped(JsonMap step) =>
recordedText(step['status']) == 'skipped' ||
recordedText(step['outcome']) == 'skipped';
String _noSessionMessage(JsonMap step) {
final status = _text(step['status']);
if (status == 'skipped' || _text(step['outcome']) == 'skipped') {
return visitSessionSkipped;
}
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<Map> _exportEvidence(JsonMap step) {
final repairs = <Map>[];
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 = <Map>[];
void add(Map entry) {
for (final candidate in ordered) {
if (identical(candidate, entry)) return;
}
ordered.add(entry);
}
for (final repair in repairs) {
if (_isComplete(repair)) add(repair);
}
if (original is Map && _isComplete(original)) add(original);
for (final repair in repairs) {
add(repair);
}
if (original is Map) add(original);
return ordered;
}
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' &&
_positive(evidence['messages']) &&
_positive(evidence['html_bytes']) &&
evidence['truncated'] != true &&
_text(evidence['diagnostic']) == null;
bool _positive(dynamic value) {
if (value is num) return value > 0;
if (value is String) return (int.tryParse(value.trim()) ?? 0) > 0;
return false;
}
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;
}
+151
View File
@@ -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 `<status> · <n> 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 <file>` 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.
@@ -0,0 +1,258 @@
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/api_gateway.dart';
import 'package:pipelines_app/features/runs/ui/run_detail_visit_session.dart';
import 'package:pipelines_app/features/runs/ui/run_detail_visit_session_state.dart';
import 'run_detail_visit_support.dart';
Future<void> pumpSessionExport(WidgetTester tester, JsonMap step) =>
tester.pumpWidget(
MaterialApp(
home: Scaffold(
body: RunVisitSession(
step: step,
configuredEndpoint: 'ws://example.test/connect',
),
),
),
);
JsonMap sessionStep() => firstVisitStep(visitRunFixture());
JsonMap artifact(String name) => <String, dynamic>{
'name': name,
'url': 'https://example.test/artifacts/$name',
'content_type': 'text/html',
'size_bytes': 100,
};
void main() {
testWidgets('a verified export reports complete', (tester) async {
await pumpSessionExport(tester, sessionStep());
expect(find.text('complete'), findsOneWidget);
expect(find.text('partial'), findsNothing);
expect(find.textContaining('full session evidence'), findsNothing);
expect(find.text('Reason'), findsNothing);
});
testWidgets('a partial export keeps the server status and its reason', (
tester,
) async {
final step = sessionStep();
step['session_export'] = <String, dynamic>{
'html': 'session.html',
'status': 'failed',
'messages': 2,
'diagnostic': 'The native read was refused.',
};
await pumpSessionExport(tester, step);
expect(find.text('partial'), findsOneWidget);
expect(
find.textContaining(
'This export is failed; full session evidence is not available.',
),
findsOneWidget,
);
expect(find.text('The native read was refused.'), findsOneWidget);
});
testWidgets('complete status without evidence is not promoted to complete', (
tester,
) async {
final step = sessionStep();
step['session_export'] = <String, dynamic>{
'html': 'session.html',
'status': 'complete',
'messages': 0,
'html_bytes': 0,
'diagnostic': 'Bounded read returned no messages.',
};
await pumpSessionExport(tester, step);
expect(find.text('complete'), findsNothing);
expect(find.text('partial'), findsOneWidget);
expect(find.text('Bounded read returned no messages.'), findsOneWidget);
});
testWidgets('an export with no recorded evidence stays unknown', (
tester,
) async {
final step = sessionStep()..remove('session_export');
await pumpSessionExport(tester, step);
expect(find.text('unknown'), findsOneWidget);
expect(find.text('complete'), findsNothing);
});
testWidgets('a missing export reports missing and the server reason', (
tester,
) async {
final step = sessionStep();
step['session_export'] = <String, dynamic>{
'html': 'session.html',
'status': 'failed',
'diagnostic': 'The export file was not listed.',
};
step['artifacts'] = <dynamic>[artifact('plan.csv')];
await pumpSessionExport(tester, step);
expect(find.text('missing'), findsOneWidget);
expect(
find.textContaining('The export file was not listed.'),
findsOneWidget,
);
expect(find.textContaining('Open '), findsNothing);
});
testWidgets('a skipped visit reports skipped and its recorded sentence', (
tester,
) async {
final step = sessionStep();
step['status'] = 'skipped';
step['outcome'] = 'skipped';
step
..remove('session_id')
..remove('session_export')
..remove('artifacts');
await pumpSessionExport(tester, step);
expect(find.text('skipped'), findsOneWidget);
expect(find.text(visitSessionSkipped), findsOneWidget);
});
testWidgets('recorded repairs and their open labels stay read-only', (
tester,
) async {
final step = sessionStep();
step['session_export'] = <String, dynamic>{
'html': 'session.html',
'status': 'failed',
'messages': 0,
'diagnostic': 'The first export failed.',
};
step['session_export_repairs'] = <dynamic>[
<String, dynamic>{
'html': 'session-repair-1.html',
'status': 'failed',
'messages': 0,
'diagnostic': 'The first repair failed.',
},
<String, dynamic>{
'html': 'session-repair-2.html',
'status': 'complete',
'messages': 3,
'html_bytes': 500,
},
];
step['artifacts'] = <dynamic>[
artifact('plan.csv'),
artifact('session.html'),
artifact('session-repair-1.html'),
artifact('session-repair-2.html'),
];
await pumpSessionExport(tester, step);
expect(find.text('repair'), findsOneWidget);
expect(
find.text('failed · 0 messages. The first repair failed.'),
findsOneWidget,
);
expect(find.text('complete · 3 messages.'), findsOneWidget);
expect(find.text('Open repaired export'), findsOneWidget);
expect(
find.widgetWithText(TextButton, 'Open repaired export'),
findsNothing,
);
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'] = <dynamic>[
<String, dynamic>{
'html': 'session-repair-1.html',
'status': 'failed',
'messages': 0,
'diagnostic': 'The repair read failed.',
},
];
step['artifacts'] = <dynamic>[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'] = <String, dynamic>{
'html': 'session.html',
'status': 'quarantined',
'diagnostic': 'The server quarantined this export.',
};
step['artifacts'] = <dynamic>[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'] = <String, dynamic>{
'html': 'session.html',
'status': 'quarantined',
'diagnostic': 'The server quarantined this export.',
};
await pumpSessionExport(tester, step);
expect(find.text('quarantined'), findsOneWidget);
expect(find.text('complete'), findsNothing);
expect(find.text('The server quarantined this export.'), findsOneWidget);
});
}
+63 -1
View File
@@ -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() => <String, dynamic>{
'name': 'Release verification',
'stages': <dynamic>[
@@ -109,6 +111,66 @@ JsonMap _run() => <String, dynamic>{
'target': '#success',
'diagnostic': 'Built.',
},
<String, dynamic>{
'stage': 'audit',
'sequence': 3,
'status': 'completed',
'outcome': 'success',
'target': '#success',
'diagnostic': 'Audited.',
'session_id': 'sess-2',
'session_export': <String, dynamic>{
'html': 'session.html',
'status': 'complete',
'messages': 3,
'html_bytes': 500,
},
'session_export_repairs': <dynamic>[
<String, dynamic>{
'html': 'session-repair-1.html',
'status': 'failed',
'messages': 0,
'diagnostic': 'The repair read failed.',
},
],
'artifacts': <dynamic>[
<String, dynamic>{
'name': 'session.html',
'url': 'https://example.test/artifacts/session.html',
'content_type': 'text/html',
'size_bytes': 100,
},
<String, dynamic>{
'name': 'session-repair-1.html',
'url': 'https://example.test/artifacts/session-repair-1.html',
'content_type': 'text/html',
'size_bytes': 100,
},
],
},
<String, dynamic>{
'stage': 'partial',
'sequence': 4,
'status': 'completed',
'outcome': 'success',
'target': '#success',
'diagnostic': 'Partial export recorded.',
'session_id': 'sess-3',
'session_export': <String, dynamic>{
'html': 'session.html',
'status': 'failed',
'messages': 2,
'diagnostic': 'The native read was refused.',
},
'artifacts': <dynamic>[
<String, dynamic>{
'name': 'session.html',
'url': 'https://example.test/artifacts/session.html',
'content_type': 'text/html',
'size_bytes': 100,
},
],
},
],
};
+107 -3
View File
@@ -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=<probe build> \
@@ -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');