# Five-Dimension Synthesis for a Future Trajectory Manager This document follows the five dimensions supplied by the project owner. It is an observation and design-research synthesis, not an implementation plan or an adoption claim. The dependency order is important: ```text overall data management ├─ single-case detail │ └─ per-epoch inspection │ └─ HTML process replay └─ case/run comparison ``` Without stable data identity, the other four views can show internally inconsistent evidence even if each individual screen looks correct. ## Dimension 1 — Overall Data Management ### What v-harness presents now The Gallery is the runnable input inventory; Database is the completed archive; `/current` is the active execution pointer; live workspaces and archived runs are separate storage layers. Screenshot 03 shows inputs, screenshots 05/16 show the archive, and the API/source map explains the three lifetimes. ### Valuable details to learn - Repeated runs do not overwrite each other in `_runs//`. - Every active run receives a fresh isolated workspace. - Gallery marks known accepted/rejected cases and can fall back to an existing render thumbnail. - Database puts target and reproduction together at scan time. - Batch selection is extremely lightweight and concurrency is one click away. - A refresh can reattach to an in-memory current job or batch. ### Current limitations - Database is a flat card grid with no filters, search, source version, model, timestamps, batch identity, tags, artifact completeness or provenance. - `case`, `job_id`, `case.n`, `case~n` and newest live workspace are different identities, but the UI does not teach or consistently preserve them. - Debug/Pipeline opened from an old archive card may inspect the newest live run. - Batches and Job event buffers are not durable after process restart. - “Rejected”, “complete”, “artifact missing” and “infrastructure error” are not represented as independent state dimensions. - Delete is hover-only, recursive and irreversible. ### Data contract a future manager would need | Entity | Minimum stable fields | | --- | --- | | External source version | project, branch, fixed commit, release, source URL | | Case | case id, dataset/suite, input artifact, dimensions, tags, sensitivity | | Run | immutable run id, case id, source version, created/finished time, model/config, batch id, lifecycle, stop reason | | Artifact | artifact id, run id, role, path/URL, media type, checksum, completeness, visibility | | Verdict | run/epoch id, gate type, pass/fail, issue counts, evidence refs, evaluator version | | Event | event id, run id, epoch id, sequence, time, type, group, tool, summary, evidence refs | | Comparison set | id, ordered run/case members, alignment mode, saved annotations | Infrastructure lifecycle, artifact completeness, model verdict and evidence quality should be separate fields. A gate FAIL can coexist with a healthy deployment; an absent render can coexist with a stored result. ### Future merge question Can the internal manager make immutable run identity the only input accepted by detail, comparison, epoch and replay views, while treating “latest run” as an explicit query rather than a hidden resolver? Status: `observed`. ## Dimension 2 — Single-Case Detail ### What v-harness presents now One case's story is split across: - Gallery card: identity, target thumbnail and coarse verdict. - Main workbench: live events, current target/render and final summary. - Fullscreen compare: large target ↔ reproduction. - Debug: DOM/image/strategy evidence. - Pipeline: grounding and per-epoch gate evidence. - Backend-only log/artifact routes: raw run log, events and CLI streams. The depth is excellent, but there is no stable “case/run dossier” entry point. ### Valuable details to learn - Target and reproduction remain visible beside live work. - Final summary answers verdict, elapsed, epochs, tools and two failure families in one compact card. - Debug separates exact rendered evidence from estimated grounded evidence. - Strategy view makes crop/inpaint choices visible instead of hiding them inside a transcript. - The list ↔ box cross-highlighting is a precise inspection interaction. - Pipeline keeps original visual questions and answers, not only a score. ### Current limitations - Clicking a Gallery card starts compute instead of opening existing detail. - Database card has no explicit detail action; its whole-card action only opens visual comparison. - There is no URL/deep link for a specific immutable run dossier. - Run config, source version, timestamps, raw artifacts, logs and event counts are not available in one place. - Debug and Pipeline can point to different run identity than the archived comparison from which they were launched. - The current main comparison shows broken empty images before a case is active. ### Information structure for a future case/run dossier 1. Identity bar: case, immutable run, source version, model/config, lifecycle, gate verdict, artifact completeness. 2. Overview: target, final reproduction, concise outcome and primary issue families. 3. Trajectory: epoch chapters and event/replay entry. 4. Verification: spatial, visual, grounding and evaluator provenance. 5. Construction strategy: HTML blocks, crop/inpaint assets, relative/absolute structure and other task-specific mechanisms. 6. Artifacts and logs: named files, checksums, readable logs and raw downloads, subject to access policy. 7. Relationships: batch membership, earlier/later runs of the same case, comparison sets and annotations. ### Future merge question Which information belongs above the fold for triage, and which belongs in progressive detail, so the page serves both “is this run healthy?” and “why did this exact epoch fail?” without recreating the current fragmentation? Status: `observed`. ## Dimension 3 — Case / Run Comparison ### What v-harness presents now Fullscreen comparison is strong for one target versus one reproduction (screenshot 06). It gives equal panes, sticky labels, synchronized scroll and a fit mode. Pipeline frames reuse this component to compare an epoch against the same target. There is no native case ↔ case, run ↔ run, version ↔ version or epoch ↔ epoch comparison workspace. ### Valuable details to learn - Equal visual weight and synchronized navigation reduce comparison effort. - Reusing one comparison overlay from Database, current result and Pipeline keeps behavior consistent. - The target remains the common anchor for epoch inspection. ### Current limitations - A comparison cannot be saved, named, shared or reopened. - No selection basket connects Gallery/Database cards to a comparison set. - No metadata, verdict, metric, issue or tool-count columns accompany images. - No pixel/diff/overlay mode, viewport normalization or annotation layer. - No support for comparing different cases with different target dimensions. - Layered overlay Escape behavior can lose the context from which comparison was opened. ### Comparison modes a future manager should distinguish | Mode | Question | | --- | --- | | Target ↔ reproduction | How close is one run to its source? | | Run A ↔ Run B on same case | What changed across model/config/version? | | Epoch N ↔ Epoch N+1 | What did this epoch actually change? | | Case A ↔ Case B | Do two tasks expose the same failure/mechanism pattern? | | Aggregate cohort | Which cases share a verdict, issue or trajectory shape? | Each mode needs explicit alignment semantics. “Sync scroll” is sufficient only when canvases correspond; other cases may need fit, normalized coordinate, overlay, diff or independent navigation. ### Future merge question Should the primary comparison object be an ordered set of immutable runs, with case and epoch views projecting from it, instead of a transient pair of image URLs passed to a modal? Status: `observed`. ## Dimension 4 — Per-Epoch Inspection ### What v-harness presents now Pipeline shows grounding, then one card for every epoch. Each epoch includes: - snapshot and PASS/REJECT; - tool total and grouped counts; - elapsed time; - full spatial issue list; - full visual question bank with expected/actual/reason; - click-through target comparison. Screenshots 10 and 11 provide the strongest evidence. The no-epoch state is captured in screenshot 18. ### Valuable details to learn - Epoch is a first-class chapter, not merely a timestamp in one long log. - Gate evidence stays attached to the exact epoch snapshot. - Tool groups summarize the work pattern before the user reads raw calls. - Visual mismatches retain falsifiable questions and answers. - Grounding is a separate truth stage before generated epochs. ### Current limitations - Only the final epoch metadata JSON is summarized; there is no step-by-step change explanation inside the epoch. - Cards are fixed 300 px and details are individually scrollable, which makes cross-epoch comparison difficult for many epochs. - Spatial detail can dominate the card and hide visual evidence below. - Aggregate tool count (127) differed from persisted tool-call count (143) in the canary, but the UI does not reveal scope/provenance. - The timeline route resolves newest live workspace, not selected archive. - No stable `epoch_id`, direct link or annotation/bookmark. ### Epoch contract a future manager would need - immutable `epoch_id` within immutable `run_id`; - start/end time and duration; - input artifact and output artifact identities; - ordered event range; - event/tool group counts with counting scope; - before/after/diff frame references; - gate/evaluator version, decision, structured issues and raw evidence refs; - termination reason: passed, retry, max epochs, stop or infrastructure error; - human annotations and comparison membership. ### Future merge question Can epoch cards remain scannable while a selected epoch opens a deeper event timeline, instead of forcing every raw issue into every horizontal card? Status: `observed`. ## Dimension 5 — HTML Animated Process Replay ### What v-harness presents now Two existing ingredients are close but incomplete: - the live event stream narrates assistant text, every tool call/result, grounding, gates and errors; - the persisted run contains sequential render frames and epoch snapshots. Pipeline is a static storyboard, not a player. Raw logs are available through a protected route but have no replay surface. ### What “HTML video” should mean The future surface should be an interactive, deterministic HTML replay, not a pre-rendered video file. The user should be able to: - play/pause and choose speed; - step backward/forward one semantic event; - scrub a timeline with epoch and gate chapter markers; - filter reasoning, perception, mutation, execution, errors and gates; - keep target, current render and event narration synchronized; - open the exact artifact/log evidence for the selected step; - jump from a gate issue back to the event(s) that introduced or attempted to repair it; - share a deep link to run + epoch + step without exposing private data. ### “Every step did what?” narration contract | Field | User-facing question | | --- | --- | | Sequence/time | When did it happen? | | Epoch/chapter | Which loop iteration owns it? | | Actor/type/group | Who or what acted? Perceive, execute, mutate, gate? | | Intent summary | What was it trying to do? | | Tool/input summary | What operation and parameters were used? | | Result summary | What came back? Was it successful? | | Before/after artifact | What visibly changed? | | Evidence reference | Which frame, log, bbox, question or file proves it? | | Causal link | Which previous evidence prompted this step? | | Next decision | Why did the loop continue, stop or retry? | ### Frame/event alignment problem The audited run has 143 tool calls, 361 events, 63 intermediate render frames and one epoch snapshot. A naive slideshow cannot truthfully say that every step has a unique visual frame. The replay needs explicit alignment: - events that do not change the artifact keep the previous frame; - one event may produce a new frame; - several low-level events may be grouped into one semantic step; - gate frames and final frames require named roles; - timestamps and event sequence remain authoritative even when a frame is absent. ### Minimum replay state machine ```text load immutable run → validate event/artifact references → build epoch chapters → derive semantic steps without deleting raw events → align each step to previous/current frame → play / pause / seek / filter → deep-link selected run + epoch + step ``` Derived narration must never replace raw evidence; it is an index over it. ### Future merge question What is the smallest deterministic step-grouping rule that makes a 361-event run understandable without inventing causal explanations or hiding recoverable errors? Status: `observed`. ## Cross-Dimension Decision Gate Before any merge project begins, require all five answers: 1. What is the immutable run identity and provenance contract? 2. What is the canonical single-run dossier route? 3. What entities can enter a saved comparison set and how are canvases aligned? 4. What is the epoch identity and evidence contract? 5. How are raw events grouped and aligned to frames without losing evidence? Until those questions are answered and prototyped against at least multiple runs of the same case plus multiple cases, every mechanism remains observed.