# A4 — turn documents in the artifact gallery ## Scope The run-detail Artifacts page now lists a visit's turn documents beside its stage files: `input.md`, `memory.md`, `output.md` and `session.html`. They are entries of the visit group, not a separate run-level list. ## Behaviour - A recorded document is a normal gallery row with the server's exact recorded name, MIME and byte size. Selecting it uses the same `ArtifactSelectionFacts` and URL-state rules as a stage file. - Markdown documents (`input.md`, `memory.md`, `output.md`) open in the existing in-app artifact viewer and join its recorded paging order. - `session.html` is external-only by name. It always takes the selection dialog with the existing Open/Copy actions, even when the server sniffed it as `text/plain`; it is never fetched or drawn in the renderer. - A document the visit did not record keeps its row with the exact audit words: `No input recorded.`, `No memory recorded for this visit.`, `No output recorded.`, and the web session wording (for example `This visit has no harness session.` or `Session ses-42 is recorded. Its export is not yet available.`). The missing row is not tappable. - Nothing is synthesized: a document exists only when its exact recorded name is in the step's artifact list. Step fields named `input`/`memory`/`output` are ignored. An absent artifact capture yields no document slots, and a visit that recorded none of the four documents shows no document section rather than four fabricated absences. - The run header count now counts stage files plus recorded documents; absent slots are never counted. Stage-only grouping (`artifactGroups`) is unchanged. ## Files | File | Lines | Responsibility | | --- | ---: | --- | | `lib/features/artifacts/domain/artifact_document.dart` | 153 | Document slots, exact absence wording, exact-name lookup, external-only/viewer eligibility | | `lib/features/artifacts/domain/artifact_groups.dart` | 160 | `galleryGroups` merging stage groups with per-visit documents; recorded count | | `lib/features/artifacts/domain/gallery_navigation.dart` | 91 | Viewer paging includes recorded markdown documents, excludes session exports | | `lib/features/artifacts/domain/artifact_record.dart` | 85 | Turn-file vocabulary and recorded record model | | `lib/features/artifacts/domain/artifact_summary.dart` | 81 | Header counts recorded gallery entries | | `lib/features/artifacts/ui/artifact_row_labels.dart` | 32 | Shared group/name/facts labels and identity | | `lib/features/artifacts/ui/artifact_record_row.dart` | 82 | Native Material/Cupertino recorded row | | `lib/features/artifacts/ui/artifact_document_section.dart` | 124 | Per-visit document rows and exact absence rows | | `lib/features/artifacts/ui/artifact_visit_list.dart` | 128 | Group list composing stage rows and document sections | | `lib/features/artifacts/ui/artifact_gallery_page.dart` | 277 | Uses gallery groups; session export bypasses the viewer | | `lib/features/artifacts/ui/artifact_selection_facts.dart` | 71 | Same facts panel with the recorded-entry count | | `lib/features/artifacts/ui/artifact_viewer_body.dart` | 248 | Material pager wraps instead of clipping | | `test/features/artifacts/domain/artifact_document_test.dart` | 281 | Exact records, all absence words, no synthesis, grouping, paging | | `test/features/artifacts/ui/artifact_gallery_documents_test.dart` | 183 | Both hosts: entries, grouping, missing wording, row semantics, viewer, external-only session | | `tool/artifact_gallery_probe.dart` | 385 | New isolated `documents` fixture state | | `tool/artifact_gallery_probe.mjs` | 936 | Real-browser A4 checks, contrast, pager geometry and captures | ## Fixes after the review stages - **Material absence rows use normal text contrast.** The absent-document row is no longer a disabled `ListTile`. It keeps no `onTap` (still non-actionable) but paints the explanation with the theme's `onSurfaceVariant`, like every other secondary label. Measured from 3x rasterised pixels: **8.88:1** in light mode and **10.91:1** in dark mode (previous: 2.67:1 and 3.64:1). - **Material viewer pager no longer clips at 320 px/2x.** The fixed `Row` became a `Wrap`, so at 320 px with 2× text `Previous artifact` (x=8, w=236.4) and `Next artifact` (x=8, w=186.1) each take their own line and stay inside the viewport (previous: Next ended at 430.6 px). This also fixes the pre-existing stage-artifact pager case. - Quality follow-ups from the code review: the changed files are `dart format` clean; `turnDocumentNames` is aliased to `systemArtifactNames`; `visitDocuments` parses the capture once; the external-only session is detected by its domain name (`sessionExportDocumentName`) instead of object identity; the stale `artifact_summary`/`artifact_record` comments now match the gallery surface. - Tests now pin every `sessionDocumentAbsence` branch (skipped, canceled, interrupted, running, failed with/without diagnostic, runtime error, pending recovery, complete-inventory, evidence diagnostic), the absent row's non-actionable but enabled Material tile and secondary colour, and the 320 px/2× Material pager geometry. ## Checks - `flutter analyze`: clean (`No issues found!`). - `dart format --output=none --set-exit-if-changed` on every changed/new Dart file: clean. - `flutter test test/features/artifacts`: 148 pass. - `flutter test` (integrated): 1049 pass. - `flutter build web`: succeeds. - Probe build: `flutter build web --target tool/artifact_gallery_probe.dart --output build/probe-a4-fix`. - Real headless Chrome probe: 36 checks, 41 captures, 0 failures. A4 captures: `a4-material-documents`, `a4-material-session`, `a4-material-document-viewer`, the same three for Cupertino, `a4-material-light-absence-row`, `a4-material-dark-absence-row` and `a4-material-320-2x-document-viewer`. Inspected the light/dark absence pages (legible, no disabled dimming), the 320/2× document viewer (both pager controls whole, wrapped) and the Cupertino document list (unchanged native grouped rows). - Evidence: `public/a4-code-fix/evidence.json` plus the captures above. The probe serves only its own loopback fixture. No server, operator run or authenticated production data was touched. ## Known limits - Not committed: this stage is read-only for history, so the candidate is left in the worktree for the landing stage. - Repaired session exports (`session-repair-*.html`) are still not resolved; the web client prefers the verified repair, and `PARITY.md` still lists this as deferred. A repaired visit can show `session.html` or the "not available in the artifact inventory" wording instead of the repair. - The dialog still offers Download/Share for an external-only session export; external-only here means it cannot be rendered in-app, not that its bytes are unavailable. - Mobile (Android/iOS) rendering and OS behavior remain unverified; only web was tested.