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

6.8 KiB
Raw Blame History

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.