Merge branch 'main' into flutter/s1-list
This commit is contained in:
@@ -0,0 +1,101 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,116 @@
|
||||
# P2c — deterministic orthogonal edge and label routing
|
||||
|
||||
## What changed
|
||||
|
||||
New app-only, pure-Dart files. No existing file, server, web client, legacy
|
||||
client, shell, `main.dart`, pubspec, domain, layout, other feature or platform
|
||||
source was edited.
|
||||
|
||||
| File | Lines | Responsibility |
|
||||
| --- | --- | --- |
|
||||
| `lib/features/graph/routing/route_models.dart` | 261 | public route, port, label, diagnostic and bounds types |
|
||||
| `lib/features/graph/routing/routing_inputs.dart` | 64 | measured label extents and caller clearances |
|
||||
| `lib/features/graph/routing/route_geometry.dart` | 175 | axis track allocator and column-gap bands |
|
||||
| `lib/features/graph/routing/corridor_plan.dart` | 105 | vertical corridor allocation per column gap |
|
||||
| `lib/features/graph/routing/edge_route_planner.dart` | 265 | forward/back/same-rank/self-loop polyline planning |
|
||||
| `lib/features/graph/routing/edge_label_placement.dart` | 175 | measured label boxes clear of nodes and other labels |
|
||||
| `lib/features/graph/routing/graph_edge_routing.dart` | 135 | validation, skipped diagnostics, labels, total bounds |
|
||||
| `test/features/graph/routing/routing_fixtures.dart` | 143 | chain/diamond/parallel/cycle/self-loop/disconnected fixtures |
|
||||
| `test/features/graph/routing/routing_assertions.dart` | 215 | orthogonality, borders, node interiors, corridors, labels, bounds |
|
||||
| `test/features/graph/routing/graph_edge_routing_test.dart` | 191 | chain, diamond, parallel, cycle, loop, disconnected, expanded text, unknown targets |
|
||||
| `test/features/graph/routing/graph_routing_geometry_test.dart` | 161 | wide labels, tight gaps, 3-stage SCC, backward layout, loop + forwards |
|
||||
| `test/features/graph/routing/graph_routing_validation_test.dart` | 222 | empty input, missing measurements, duplicate ids, invalid config, determinism/immutability |
|
||||
|
||||
No painting, widgets, styling, shell wiring or font/CSS/device constants were
|
||||
added.
|
||||
|
||||
## Public API
|
||||
|
||||
```dart
|
||||
GraphRouting routeGraphEdges({
|
||||
required GraphLayout layout,
|
||||
required List<GraphEdge> edges,
|
||||
required Map<int, LabelExtent> labelExtents,
|
||||
required RoutingConfig config,
|
||||
});
|
||||
```
|
||||
|
||||
`RoutingConfig` takes `nodeClearance`, `laneSpacing`, `corridorSpacing`,
|
||||
`portSpacing`, `labelGap` and optional `boundsPadding`. `LabelExtent` is the
|
||||
caller's measured label width/height. The node boxes and ranks are the landed
|
||||
`GraphLayout` values; the router never moves or resizes a node.
|
||||
|
||||
`GraphRouting` exposes unmodifiable `routes`, `labels`, `skipped`, `width` and
|
||||
`height`, plus `routeFor(id)` / `labelFor(id)`. Each `EdgeRoute` keeps the
|
||||
definition `id`, `source`, `outcome`, `target`, `label` and `fallback` flag, and
|
||||
returns `sourcePort`, `targetPort`, a `RouteKind` and an orthogonal `points`
|
||||
list. Each `EdgeLabelBox` carries the measured box for its edge id.
|
||||
|
||||
## Deterministic guarantees (and what is not claimed)
|
||||
|
||||
- **Identity:** routed edges copy the definition identity unchanged; skipped
|
||||
edges keep it in `RouteDiagnostic` with `unknownSource`/`unknownTarget`. No
|
||||
node, route or visit is invented for an empty, missing or unknown target.
|
||||
- **Order and stability:** routes, labels and diagnostics are ordered by edge id
|
||||
regardless of input order. Equal input produces equal, immutable results.
|
||||
- **Orthogonality and ports:** every consecutive point pair shares one
|
||||
coordinate. Endpoints are exactly on the source/target border with the
|
||||
recorded side: forward routes leave right and enter left; same-rank, backward
|
||||
and self-loop routes leave/enter the right side.
|
||||
- **Node avoidance:** a forward one-rank route is a straight horizontal run only
|
||||
when the boxes share a port band and leave room for label-aware track spacing.
|
||||
Every other route drops into a unique horizontal lane below the node grid,
|
||||
travels vertically only inside column gaps (or the free space right of the
|
||||
last column), and returns to a port through its own stub. Vertical corridors
|
||||
and lanes never enter a node column, and every horizontal stub stays on a row
|
||||
that is clear of unrelated node boxes.
|
||||
- **Distinguishable runs:** vertical tracks are spread across each gap, one
|
||||
slot per corridor request; horizontal stubs and straight routes share one
|
||||
interval-aware allocator; every wrapping route owns its own lane. Two edges
|
||||
cannot share a collinear run in the tested fixtures.
|
||||
- **Labels:** each routed edge needs a measured `LabelExtent`; a missing one is
|
||||
an `ArgumentError`. The box is placed at a deterministic route run, clear of
|
||||
node interiors and earlier labels. If a run is too narrow (for example a wide
|
||||
label between close columns), the label moves to a free shelf below the
|
||||
drawing and the returned bounds grow instead of covering a node.
|
||||
- **Bounds:** `width`/`height` include the landed node layout, all route points
|
||||
and all label boxes, plus `boundsPadding`. A self loop or an edge into the
|
||||
right-free gap expands the box; nothing is clipped.
|
||||
- **Not claimed:** perfect general crossing minimization or minimal bend
|
||||
counts. Corridors and lanes are deterministic and locally separated, not a
|
||||
globally optimal routing.
|
||||
|
||||
## Checks actually run
|
||||
|
||||
```
|
||||
flutter pub get
|
||||
dart format lib/features/graph/routing test/features/graph/routing # 0 changed
|
||||
flutter test test/features/graph/routing # 20 passed
|
||||
flutter analyze # No issues found!
|
||||
flutter test # 193 passed
|
||||
```
|
||||
|
||||
Focused coverage includes chain, diamond fan-out/fan-in, three outcomes to one
|
||||
target, a two-stage and a three-stage SCC, a self loop alone and beside forward
|
||||
routes, disconnected stages, heterogeneous widths, 2.6x expanded text, tight
|
||||
gaps, wide labels, a caller-supplied backward rank, missing/empty/unknown
|
||||
targets, immutability, stable ordering and finite bounds.
|
||||
|
||||
## Honest limits
|
||||
|
||||
- **No rendering.** This is a nonvisual geometry slice: no painter, widgets,
|
||||
native controls, screenshots or browser behavior. Rendered parity belongs to
|
||||
the next renderer task.
|
||||
- **Layout is an input.** The router does not widen columns for labels or move
|
||||
nodes. Very wide labels may sit on the free shelf below the drawing; callers
|
||||
that want labels beside an edge should reserve enough column gap when laying
|
||||
out nodes. A zero-width column gap leaves no space for distinct vertical
|
||||
corridors, so callers should supply a positive gap (the landed layout keeps
|
||||
whatever gap it is given).
|
||||
- **No general crossing optimum.** Only deterministic corridor/lane separation
|
||||
is guaranteed, as described above.
|
||||
- **No server or device.** Tests use local fixtures only; no run, pipeline,
|
||||
schedule, service, emulator, ADB, Android/iOS build or live chat was touched.
|
||||
- **Mobile unverified.** Only web-targeted Flutter test/analyze ran.
|
||||
- **Uncommitted candidate.** Per this stage's instruction the slice is left in
|
||||
the worktree; no commit, push or deployment was made.
|
||||
Reference in New Issue
Block a user