Files
pipelines/app/notes/A4-docs.md
T

111 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.