Skip to content

Milestone 1, step 1: the diagram

Authority: plan. This page says what the first piece of the application is, how each part of it is checked, and in what order it is built. It is short-lived: when the last goal is done, what it decided is folded into ARCHITECTURE.md and the mapping record, and this page is removed.

The outcome

Open a SACM 2.3 file in the desktop application or the web application and see its argument as a GSN diagram in the middle of a DATUM workspace that has left, right and bottom panels. Pan, zoom, fit and select. The selected element's details show in the right panel. Nothing is edited.

It is the first step of milestone 1 (View) in the Phase 0 release plan, and it also runs the open Phase 0 spike "one core, two targets".

Done when

  1. testdata/sacm/sacm_example_core_argument.sacm.xmi opens in the desktop application and in the browser build, and draws the view in the expected view below. The other four samples open too, by a strict read (D8).
  2. Every interaction under Interaction works, each with an automated check in the browser build.
  3. testdata/sacm/safety-case-sanitized-strict.sacm.xmi (1,090 elements, the largest file libSACM reads today) opens and pans and zooms within the budgets.
  4. A file libSACM refuses shows the refusal, worded in the interface language from its code and arguments, with its line and column, and no diagram.
  5. CI is green, and ARCHITECTURE.md says what is built. CI cannot install DATUM, so the interface checks (pnpm --dir ui check and e2e) run on the development machine and their results go in each pull request.

Out of scope

Editing, undo and save. The tree in the left panel and the problem list in the bottom panel: the panels are there, titled and empty. SVG export. Modules, patterns, assurance claim points and challenges. Those come in the next steps of milestone 1 and in milestone 2.

The pieces

Piece Crate or folder New in this step
The SACM model sacm 0.2 from crates.io dependency
GSN view of a document af-gsn the view and its reading rules
Text measurement, layout, render model af-layout crate
The frontend contract af-api crate, holding the open document
Browser wrapper af-wasm crate
Desktop shell af-desktop crate
Interface ui/ React, DATUM, the canvas

af-session is not added yet. With nothing edited there is one revision, and af-api holds the document. The session crate arrives with the first edit, when it has a change stream to own.

Decisions this plan takes

Agreed in the tracking issue, #493, on 18 November 2026. D5, D6 and D8 were revised that day, when DATUM and libSACM had delivered what they waited for.

# Decision Why
D1 Desktop and web from the first step, and the web build is the test target. Both are products (ARCHITECTURE.md, goal 5). The same ui/ runs on af-desktop in Tauri and on af-wasm in a browser, behind one Core interface with two implementations. Automated interface checks drive the web build with Playwright in Chromium, Firefox and WebKit. The desktop application gets a smoke check. Driving a desktop window is slow and fragile; the C++ application's GUI driver cost hours to locked sessions and stolen focus. WebKit in Playwright is also the nearest automated stand-in for Tauri on macOS and Linux, which the canvas spike could not test.
D2 Reading rules are written down before they are coded. How each SACM element and relationship is drawn in GSN is a new section of docs/standards/sacm-gsn-mapping.md, with a basis for each row. A case without evidence is drawn with a neutral shape and a code, never guessed. The mapping table says how GSN is stored in SACM. A SACM 2.3 file needs the reverse, and the reverse has ambiguous cases (see below).
D3 The view draws what the file says. If the file has an inference from an assumption, the diagram shows a SupportedBy arrow to an Assumption. Well-formedness checks report it later; the view never rearranges an argument to make it well formed. Never silently reinterpret an argument.
D4 Every argument element appears in the view exactly once: as a node, as part of an edge, or as a coded item the view could not place. A test checks this for every sample file. Nothing is dropped without a trace.
D5 The workspace is DATUM's Workspace: docks at the start, end and bottom of a centre surface, with layout state held by the application. The canvas sits in the centre surface and takes its size from onCentreSize. DATUM comes as tarballs packed locally from a DATUM checkout (pnpm --dir ui datum) and is never committed, published or fetched in CI: DATUM is private, the look of the owner's software. Others can build the core but not the DATUM interface; a plain interface for them is an open question. ui/ imports DATUM only through ui/src/design/, so a replacement has one module to stand in for. DATUM now has a shared workspace, written for Assurance Forge and Simulation Studio alike, so the application writes no docking of its own.
D6 The diagram's text uses DATUM's measured faces, DATUM Measured Sans (IBM Plex Sans) then DATUM Measured Sans JP (IBM Plex Sans JP), at 400 and 600: whole TrueType files, given to af-layout as bytes by the shell and loaded once by the page. Each character comes from the first face that has it, as in the browser; kerning applies within a run from one face. Shape with rustybuzz, break with unicode-linebreak. The interface's woff2 faces cannot be used: the shaper does not read woff2, and a face split by Unicode range loses kerning between pieces. The canvas spike's findings, and DATUM's rule for text laid out outside the browser. Not embedding the fonts in the WebAssembly package keeps it small; each Japanese weight is 5.7 MB.
D7 A simple layout first. A layered tree: SupportedBy children below their parent, InContextOf attachments beside it, siblings in document order, straight edges. The C++ src/ui/gsn/gsn_layout.cpp is the reference for spacing and placement, not code to port. A diagram that can be read beats a clever one that is late. Crossing reduction comes when real cases need it.
D8 Files open by a strict read. A file the strict read refuses shows its refusal and no diagram. A tolerant read waits for a case that needs it. Warnings from the read are counted and kept for the problem list. sacm 0.2 reads the terminology package, and all five samples now read strictly. Their only findings are warnings that a Claim has two descriptions (SACM-MULT-001).
D9 The window is arranged as the C++ application's. A menu bar, a toolbar under it, the Case Explorer and the Argument Navigator in the start dock, the diagram in the centre, Element Properties in the end dock, Problems in the bottom dock under the centre, and a status bar. Names and their Japanese are the C++ application's. Simplified: one file, not a project (Phase 0), so File ▸ Open… opens a SACM file and the Case Explorer will show that file's packages; menus offer only what works, so Edit and Add come with editing in milestone 2, and View holds Appearance ▸ Theme and Language (the C++ View menu's workbench tabs come with the workbench); panels are shown and hidden by their own Hide buttons and rails. The menu bar is DATUM's MenuBar with submenus, and the start dock stacks its two views (DATUM decisions 0024 and 0025). People who used the C++ application find their way at once. The rebuild takes its learnings, not its code. Agreed on 18 November 2026.

Reading rules (D2)

Recorded in the mapping record, docs/standards/sacm-gsn-mapping.md, under "Reading a SACM 2.3 file as GSN" (G1, #494): rules for nodes, edges and node text, each with its basis, and the codes the view sends for what it does not draw. The four rows this plan left open were decided in #493 on 18 November 2026: an axiomatic Claim is a Justification however it is reached; an asserted Claim reached only as context stays a Goal; an ArtifactReference that is not plainly evidence or context is drawn neutral with a code; and a node shows its identifier, its name and its first description in the interface language.

The expected view

Written by hand from sacm_example_core_argument.sacm.xmi, and checked by a second reader before it becomes the test's expected value.

Nodes (8) Edges (7)
Goal cl_top SupportedBy cl_top → ar_1 (via inf_1)
Strategy ar_1 SupportedBy ar_1 → cl_sub_1 (via inf_1)
Goal cl_sub_1 SupportedBy ar_1 → cl_sub_2 (via inf_1)
Goal cl_sub_2, undeveloped SupportedBy cl_sub_1 → cl_assumption_1 (via inf_2)
Assumption cl_assumption_1 InContextOf cl_top → ctx_1 (via acx_1)
Context ctx_1 SupportedBy cl_sub_1 → ev_1 (via ae_1)
Solution ev_1 SupportedBy cl_sub_2 → ev_2 (via ae_2)
Solution ev_2

Two of these are not well formed GSN: the SupportedBy to an Assumption, and an undeveloped Goal that has a Solution. They are drawn as the file says (D3).

Interaction

Action Input What happens
Pan Drag on empty canvas; middle-button drag; wheel and two-finger scroll, both axes The view moves; nothing is selected
Zoom Ctrl and wheel; pinch; + and - Zooms around the pointer (keys: around the centre), 10% to 400%; the zoom shows in the status bar
Fit Toolbar button; Shift+1; on open The whole diagram fits the canvas
Fit selection Shift+2 The selected node fits the canvas; with nothing selected, nothing happens
Actual size Shift+0 The zoom returns to 100% around the centre
Select Click a node The node is outlined; the right panel shows its GSN kind, identifier, name, statement and SACM id
Clear Click empty canvas; Esc Nothing is selected; the right panel says so
Hover Pointer over a node The node is highlighted and the cursor changes
Resize Drag a panel edge; collapse and reopen a panel The canvas fills the centre and keeps its view centre
Theme Switch dark and light The canvas redraws from DATUM tokens

The bindings are DATUM's rule for a diagram canvas. Ctrl or ⌘ with +, - and 0 stays the browser's. Selection, pan and zoom stay in the frontend. Hit testing uses the render model's geometry, the same geometry that is drawn. The canvas draws only what is in view and is sharp at any device pixel ratio. Scrolling pans on both axes because the C++ application could not scroll horizontally on a laptop (#145).

Arrow keys that move through the argument as a tree, and the accessible item per node that goes with them, come with the argument tree in the next step: the canvas and the outline move alike, so they are built together.

Budgets

On the development machine, browser build, Chromium:

Measure 24-element sample 1,090-element case
Open to first paint 200 ms 1.5 s
Native layout, release 10 ms 300 ms
Frame interval while panning, mean display interval + 10% display interval + 10%
Text width, Rust against measureText, largest error 1.5 px 1.5 px

The goals

Each goal has one check that decides whether it is done. Goals with † change how an argument is read, and get the independent review described in the loop.

Goal Outcome Check Needs
G1 † Reading rules recorded in the mapping record; the open rows decided or left drawing a neutral shape Independent review passes; the user agrees the open rows in #493
G2 † af-gsn derives a view from a sacm::Document: nodes with kind, labels and decorators; edges in GSN direction with their SACM relationship id; coded items for what it could not place cargo test -p af-gsn: the expected view, and D4 for every sample libSACM reads. cargo build -p af-gsn --target wasm32-unknown-unknown G1
G3 af-layout measures and wraps text from font bytes, sizes nodes per kind, lays out the tree, and returns a render model: shapes, text runs, edge lines with arrowhead kind, decorators. Measurements are cached per text and width. cargo test -p af-layout: output is deterministic; no two nodes overlap; edges end on their node's outline; children sit below their parent and context beside it; native layout within budget. Wasm build. G2
G4 af-api: open(bytes) answers with a revision and diagnostic counts, or a refusal: its code, template, arguments, line and column; diagram() returns the render model at the revision; element(id) returns the details panel's content. TypeScript types generated with ts-rs. cargo test -p af-api, including a test that fails when the generated types are stale. Wasm build. G3
G5 The web application: af-wasm and ui/ in a browser. Open a file by picker or drop, or a sample by URL in development. The canvas draws the render model. pnpm --dir ui check (types, lint, unit tests) and pnpm --dir ui e2e against the production build: the sample draws 8 nodes and 7 edges G4
G6 The workspace: DATUM's Workspace with start "Outline", end "Details", bottom "Problems", resizable and collapsible, titles in English and Japanese e2e collapses and reopens each dock and checks that the canvas fills the centre surface
G6b The C++ arrangement (D9): menu bar with File and View, toolbar, docks named and placed as in the C++ application, in English and Japanese e2e: File ▸ Open… opens the file chooser; View toggles each panel; View ▸ Appearance switches theme and language; the docks carry the C++ names in both languages G6
G7 Drawing, by DATUM's rule for a diagram canvas: GSN shapes, arrowheads (filled for SupportedBy, hollow for InContextOf), the undeveloped decorator, roles on existing tokens read with watchCanvasStyle in both themes, lines 1px at every zoom, identifiers only when zoomed far out, culling, device pixel ratio e2e: screenshot comparison per theme; text width against measureText in Chromium, Firefox and WebKit within budget, for English and for the Japanese text of oasc-ja.sacm.xmi G5
G8 Every row of Interaction e2e: one test per row, reading viewport and selection through a hook built only into test builds G6, G7
G9 af-desktop: open with a dialog or from the command line; a refused file shows its refusal and location CI builds the desktop application on Windows; a smoke test starts it with the sample and reads its log for the revision and node count G5
G10 The large case within budget e2e performance test on the 1,090-element case G8
G11 Folded back: ARCHITECTURE.md "Built" column and crate map, CI builds every pure crate for wasm, this page removed, issue closed Review of the final pull request all

G6 can start at once, beside G1 to G4: the dock needs no core.

What waits on other repositories

DATUM's workspace, measured faces and diagram canvas rule, and libSACM's codes and arguments on every refusal and diagnostic, are done. What is left:

What Needed by Until it is done
A DATUM release with Workspace, the measured faces and watchCanvasStyle G5, G6, G7 Packed from DATUM's main by ui/scripts/pack-datum.mjs, which records the commit in ui/vendor/datum/manifest.json
sacm 0.2.0 on crates.io G2 A git dependency on libSACM's main, at a pinned commit
A measured face for identifiers. DATUM's canvas rule sets them in Plex Mono, which has no whole face yet G7 Identifiers in DATUM Measured Sans at metadata size
libSACM#66 Older namespaces after this step A file in the C++ application's namespace is refused

None stops a goal from starting. Each stopgap says in the code what replaces it, and is removed when that is done.

The loop

An agent, or a person, runs the plan like this:

  1. Take the first goal whose check does not pass and whose needs are done.
  2. Make the change. Run the goal's check and the standing checks below.
  3. Show that each new check can fail: break what it checks, watch it fail, restore. A check that cannot fail checks nothing.
  4. For a † goal, a fresh agent reviews the change against the standards and the mapping record. It is given the code and the documents, not the author's conclusion.
  5. For a goal that changes the interface, a screenshot of the running application goes in the pull request.
  6. One goal, one pull request. Merge when CI is green and tick the goal in the tracking issue, #493.
  7. If a goal cannot pass without changing its check, stop and ask. Never weaken a check to pass it.

Standing checks, run every time:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
# each pure crate, from the goal that adds it:
cargo build -p af-gsn -p af-layout -p af-api --target wasm32-unknown-unknown
# from G5:
pnpm --dir ui check
pnpm --dir ui e2e

What this leaves for the next steps

  • The argument tree in the left panel, with the same view and DATUM's Tree, and arrow keys on the canvas that move through the argument as the tree does. The tree and an accessible item per node carry the structure the canvas cannot.
  • The problem list in the bottom panel: load diagnostics, well-formedness, cycles.
  • SVG export from the render model.
  • Where a second description goes. The converted samples keep a note beside the statement, which SACM 2.3 does not allow (SACM-MULT-001).
  • Opening files in the older SACM namespace that the C++ application wrote (libSACM#66).
  • Choosing the language of the diagram's text separately from the interface's.
  • Characters neither measured face has, such as emoji or Hangul. The core measures them with the missing glyph while the browser draws a system font, so such text can overflow its node. A third, measured fallback face, or a code that names the text, would close the gap.
  • Wording each of libSACM's refusal templates in English and Japanese. Until then a refusal is worded by its code, with its arguments.
  • Keeping the parsed faces between Engine::measure and wrap calls, which parse them each time; a layout parses them once.
  • Saving from the web application. The File System Access API writes back to the opened file in Chromium browsers only; elsewhere saving is a download.