# A1a — artifact records, capture facts, grouping, kinds and safe urls ## What changed New nonvisual `artifacts` domain slice. Every file is new; no existing file was edited. Nothing under `lib/main.dart`, `lib/shell/`, another feature, `pubspec.*`, `web/`, the Go server or `android/` was touched. No dependency was added and no network/transport code was written. | File | Lines | Responsibility | | --- | --- | --- | | `lib/features/artifacts/domain/artifact_record.dart` | 85 | One recorded artifact: name, url, content type, size and deeply read-only `raw`; retired `session.md` and system names | | `lib/features/artifacts/domain/artifact_capture.dart` | 63 | Per-step capture availability (`unavailable`/`recorded`), recorded files, skipped and truncated counts | | `lib/features/artifacts/domain/artifact_selection.dart` | 67 | Record parsing, retired/system/repair filtering (`presented`, `stage`, `system`) | | `lib/features/artifacts/domain/artifact_groups.dart` | 109 | Group stage artifacts by stage and recorded visit; shared `public/` attribution; per-visit list | | `lib/features/artifacts/domain/artifact_kind.dart` | 225 | MIME/extension kind vocabulary, labels, markdown/viewer predicates, `humanBytes` | | `lib/features/artifacts/domain/artifact_summary.dart` | 78 | Run/visit summary and empty wording, partial-capture flag and notes | | `lib/features/artifacts/domain/gallery_navigation.dart` | 76 | Filtered viewer page order, stable identities, previous/next clamp, position label | | `lib/features/artifacts/domain/artifact_url.dart` | 78 | Safe http(s) resolution against the configured endpoint and cross-origin marking | | `test/features/artifacts/domain/artifact_fixtures.dart` | 44 | Local step/artifact fixtures; no fake gateway or socket | | `test/features/artifacts/domain/artifact_capture_test.dart` | 241 | Unavailable/null/empty/partial capture facts and exact wording | | `test/features/artifacts/domain/artifact_groups_test.dart` | 308 | Visits, identity, retired/utility files, public attribution, empty states | | `test/features/artifacts/domain/artifact_selection_test.dart` | 154 | Field preservation, deep immutability, filtering, duplicates | | `test/features/artifacts/domain/artifact_kind_test.dart` | 110 | Known/unknown MIME and extension classification, markdown/viewer gates, bytes | | `test/features/artifacts/domain/gallery_navigation_test.dart` | 197 | Filtered order, duplicate urls/names, url-less identities, paging clamp, label | | `test/features/artifacts/domain/artifact_url_test.dart` | 148 | Relative/absolute urls, wss/https, IPv6, encoded path/query, schemes, credentials, cross-origin | ## Behaviour (from `web/src/artifacts.js` and `artifactNavigation.js`) - **Record facts are verbatim.** `ArtifactRecord.fromJson` reads `name`, `url`, `content_type`, `size_bytes` and keeps every other server field in a deep unmodifiable `raw`. A missing url stays `''`; nothing is derived from the name. Two records with the same name stay distinct because identity is the recorded url (or a visit-scoped fallback in the viewer). - **Capture availability is a recorded fact.** An absent, null or non-list `artifacts` field is `unavailable`; an explicit empty list is a recorded empty capture. `artifacts_skipped`/`artifacts_truncated` are preserved as counts and mark a partial capture. Unavailable capture never degrades to "no artifacts" or "not recorded": the run header says `Artifacts · capture unavailable` instead of `No artifacts recorded for this run.`, which is the task's explicit requirement and the one deliberate wording extension beyond the web client. - **Grouping and identity.** `artifactGroups` keeps first-appearance stage order, orders each stage's visits by sequence (recorded order on ties), and uses `displayVisit` from the existing graph domain (`control.visit` when positive, else position + 1). A step with no presented stage artifact yields no group, so unavailable/empty captures and utility-only visits never fabricate a visit. Shared `public/` files are attributed to the first recorded visit; repeated non-public names in later visits remain separate artifacts. - **Retired and utility files.** `session.md` is hidden everywhere; `session.html`, `input.md`, `memory.md`, `output.md` remain system evidence and are excluded from stage output. Repaired session exports named by `session_export_repairs` are system evidence too. - **Kinds.** Image/video come from the content type; audio, PDF, JSON, archive, spreadsheet, log, code, document then match normalised MIME or extension; unknown values are `other`/`File`. `isMarkdownArtifact`/`isViewerArtifact` keep logs, source, CSV and HTML out of the in-app viewer while images, videos and md/markdown/txt pages enter it. - **Navigation.** `pagedArtifacts` filters group by group in recorded order; `viewerIndexByUrl` maps the first occurrence of each url; url-less pages use a visit-scoped identity; `pagedIndex` clamps with no wrap; the position label trims content-type parameters and falls back to `artifact`. - **Safe urls.** Server-relative paths resolve against the configured endpoint's http(s) origin (endpoint path/query dropped, `wss` → `https`, IPv6 brackets and percent-encoding kept). Absolute http(s) urls are preserved. Output is always http(s): blank, protocol-relative, backslash-relative, hostless, credentialed, malformed and non-http(s) urls return null. A url whose origin differs from the configured origin is marked `external`, so a future authenticated fetch can refuse to send cookies or headers; a same-origin url stays internal. ## Review and quality fixes in this visit - `flutter analyze` reported four infos in this slice; all fixed: block braces in `artifact_summary.dart` and null-aware map entries (`'key': ?value`) in the test fixtures. Analyze is now clean for the whole app. - `dart format` found one unformatted test file; all 15 files are now formatted. - Semantics were re-read against `web/src/artifacts.js` (`presentedArtifacts`, `stageArtifacts`, `systemArtifacts`, `artifactKind`, `pagedArtifacts`, `viewerIndexByUrl`, `pagedIndex`, `displayVisit`) and `artifactNavigation.js`. No other concrete deviation was found, so no behaviour was rewritten. ## Checks actually run ``` flutter test test/features/artifacts/domain # 60 passed flutter test test/features/graph/domain # 41 passed (stage_visits reuse) flutter analyze # No issues found! (0.9s) dart format lib/features/artifacts test/features/artifacts # clean, 15 files grep trailing whitespace # none ``` ## Honest limits - No gallery screen, viewer, sharing, fetching or transport helper exists in this slice, so there is no rendered change and no browser capture. The gallery and viewer are separate future slices. - No live server, socket, artifact download or real run data was used; tests are local fixtures and pure functions only. - Mobile is unverified: no Android/iOS build, emulator, ADB or device was used. - **Committed by the Land stage** as `ff0f812` on `flutter/a1-data` and merged with `main` in `a303368`; the checks above were re-run on the merged candidate. This stage did not merge into `main`, push or deploy.