Skip to content
sdlc

Markdown-native workflow authoring

State: open/building · Kind: module · Audience: system

Summary

Section titled “Summary”
  • Workflows stored as markdown notes whose YAML frontmatter is the graph, with a generated mermaid diagram and steps table in the body.
  • Writes are guarded by a compare-and-swap etag and refuse to rewrite files the YAML reader would lose data from.

Statement

Section titled “Statement”

A workflow is one markdown file. Its frontmatter holds the steps, edges and layout. The body carries a mermaid flowchart and a steps table between sentinel comments, and each step can link to its own note. Reading is tolerant: input is coerced into the workflow shape and validated, and problems come back as issues. Saving regenerates the frontmatter in a fixed key order and splices only the managed body spans, so hand-written prose around them is kept byte for byte. A write must carry the etag (sha256 of the bytes last read); with no etag it succeeds only if the file does not exist. Files holding YAML aliases, tags or duplicate keys are never rewritten.

What it provides

Section titled “What it provides”
  • Workflow model with tolerant normalization and structural validation
  • Mermaid flowchart projection with id sanitising and collision rules
  • Frontmatter split, canonical emit and managed-block splice in the body
  • Step definition notes
  • Vault store: list, read, write, check and render, with path containment and atomic writes
  • Etag compare-and-swap write guard
  • Fidelity check that blocks lossy rewrites
  • Flows port implementation for the determined host

Underlying implementation

Section titled “Underlying implementation”
  • The crate at solutions/determined/crates/determined-authoring/
  • Parity with the Node designer is pinned by golden fixtures, plus a differential fuzz test that runs when its corpus is present

Locations

Section titled “Locations”
  • solutions/determined/crates/determined-authoring/
  • solutions/determined/crates/determined-authoring/src/lib.rs
  • solutions/determined/crates/determined-authoring/src/markdown.rs#parse_workflow_doc
  • solutions/determined/crates/determined-authoring/src/mermaid.rs#to_mermaid
  • solutions/determined/crates/determined-authoring/src/store.rs#guard_etag

← Back to Capabilities