The SBDL compiler: reads distributed SBDL, builds and verifies one model, and projects it into many output forms. Flat sibling modules rather than a package, so that sbdl.py stays directly runnable.

Design Goals

A quality the design is built to achieve.

Architecture

A band of modules holding one position in the import order.

Foundation

Leaf of the import graph: imports no sibling.

sbdl_core.py

Configuration, printing, progress, lazy imports and run-state reset.

Model

The language: parser, metamodel, element graph and every reader. Depends on lyr_foundation.

sbdl_model.py

Parser, semantics, element hierarchy, AST and the input layer. One module because the metamodel is internally cyclic and the parser and readers are mutually coupled.

Principles: dp_single_model, dp_immutable_elements.

Writers

Projections of a verified model into other forms; consumers of the model only. Depends on lyr_model.

sbdl_outputs.py

The output namespace: text, tabular, SQL, template and PlantUML writers, batch dispatch and trace verification. Also imports mod_openfmea, mod_sysmlv2.

Principles: dp_outputs_namespace, dp_writer_contract.

sbdl_openfmea.py

OpenFMEA import and export: the cause, mode and effect table and its portfolio form.

sbdl_sysmlv2.py

Translation of the model into SysML v2 textual notation.

sbdl_native_svg.py

Diagram-agnostic SVG basis: theme, text metrics, layouts, routing, labels and canvas.

Principles: dp_measure_equals_draw, dp_external_rasteriser.

sbdl_native_sysml.py

The native rendering backend: SysML-style diagrams drawn directly as SVG. Also imports mod_native_svg, mod_outputs.

Principles: dp_machine_readable_svg.

Services

Long-running or remote ways of reaching a compiled model. Depends on lyr_model.

sbdl_lsp.py

Language server: diagnostics, symbols, hover, completion and the model explorer snapshot.

sbdl_mcp.py

Read-only Model Context Protocol server over a compiled model.

Principles: dp_injection_over_import.

sbdl_remote.py

Standalone RPC client for the remote REST service, shipped separately from the compiler.

Entry

The command line: the only module that knows every other. Depends on lyr_writers, lyr_services.

sbdl.py

Argument handling, the mode table and the single compilation run.

Principles: dp_never_import_entry.

Assurance

Evidence that the compiler does what it claims. Depends on lyr_writers.

sbdl_compliance.py

Compliance corpus and runner that qualify an external compiler against this one. Shipped: the corpus is inline data, so it runs from an installation with no repository.

Principles: dp_semantic_comparison, dp_corpus_checks_itself.

sbdl_tests.py

The unit and integration suite, driven largely through the real command line. Not shipped: it needs the test fixtures. Holds the one sanctioned upward reference to the entry.

Principles: dp_test_through_cli.

Tooling

Build, release and editor tooling around the compiler.

helpers/

Source rewriters run on the distribution copies: explicit imports, f-string compatibility, comprehension shadowing.

release_public.sh

Publishes one commit per release to the public repository, filtered by a manifest.

Principles: dp_snapshot_releases.

build_dist.sh

Distribution build: copy, rewrite star imports, minify, repair, package.

Principles: dp_test_the_build.

Design Principles

A design decision that holds across the compiler.

Architecture

The compiler is a set of flat sibling modules, not a package. Keeps sbdl.py directly runnable however it is launched; the entry puts its own directory on sys.path first. Consequence: A bare copy of sbdl.py no longer works alone; every sibling must travel with it.
Applies to lyr_entry; serves goal_runnable

Imports form a directed acyclic graph: core, then model, then writers and services, then the entry. Each layer can be read, tested and replaced knowing only the layers beneath it. Consequence: The native renderer reaches outputs through a plain module import, the one tolerated cycle, resolved at call time.
Applies to sbdl_compiler

No module imports the entry; the test suite alone reaches it, through one guarded helper. When the entry runs as __main__, importing it re-executes it as a second module and rebuilds the configuration snapshot.
Applies to mod_entry

Modules reconstitute one shared namespace with star imports; the build rewrites them into explicit imports. Keeps the split invisible to code moved out of the original single file, while letting the minifier rename locals in the shipped copy. Consequence: Underscore names do not cross a star import and must be imported explicitly.
Applies to lyr_foundation; serves goal_correct_build; evidenced by t_distribution

Global state that must not survive a compilation registers a reset hook with the core. The language server and the test suite compile many models in one process; the core stays a leaf while any module can register state.
Applies to cmp_reset

The entry imports output modes from the outputs module and nowhere else. Adding a writer then touches only the mode table, never the entry imports. Consequence: A writer carved into its own module must be re-exported by the outputs module or the mode table fails at run time.
Applies to mod_outputs; serves goal_extensible

Semantics

Every input form is read into the same element graph, verified once, and only then projected. Writers never parse and never verify, so every output agrees on what the model is.
Applies to mod_model; serves goal_extensible

Each compilation stage ends at a gate that counts errors and aborts before the next stage. A later stage never runs on a model an earlier stage rejected, unless the user asks for that with --skip-errors.
Applies to cmp_main; serves goal_traceable

Diagnostics cite an element by source_reference, never by reference. reference is a display value a model may override; source_reference is the parser location and cannot be overridden. Consequence: The language server recovers squiggle positions from diagnostic text, so a wrong reference pins it to line 0.
Applies to cmp_elements; serves goal_traceable

Relation queries take a table of incoming relations, built once by whoever holds the element set. An element stores only the relations it declares; finding the reverse half by scanning makes every query linear and every pass quadratic.
Applies to cmp_ast; serves goal_scalable; evidenced by t_incoming_index

related is an ordinary relation, exposed through its own view and excluded from links. Relation verification type-checks each link against its target, which a related link could never satisfy.
Applies to cmp_elements

A group organises the model and is not part of it: it may end a connectivity path but never bridge one. Adding an element to a review package must not change the answer to a question about the system. Consequence: Connectivity semantics are implemented twice, in the AST walk and in the SQL query, and must change together.
Applies to cmp_ast; evidenced by t_filter_semantics

A filter reduces the model; a diagram root leaves the model whole and moves only where a diagram starts. Diagram writers reach outwards while drawing, so filtering to one element culls what is needed to draw it.
Applies to cmp_ast; evidenced by t_diagram_root

Elements are defined once and never modified; membership and relation may be declared from either side. Definitions are distributed across files the author may not own, so the model is assembled, never edited.
Applies to mod_model

Extensibility

Every output mode is one row in a mode table: name, writer, output kind, description and older spellings. Help, discovery, batch validation and the MCP tools all read the same table, so a new mode appears everywhere at once. Consequence: Deprecated spellings are kept as aliases and omitted from help, which is deprecation by omission.
Applies to cmp_mode_table; serves goal_extensible, goal_stable_cli; evidenced by t_mode_aliases

A writer takes the AST, the output path, a file opener, the arguments and a print function, and returns an error count. One signature lets the entry, batch, the MCP server and custom modes all drive any writer the same way. Consequence: A writer reads its own mode name from the arguments, never from a literal of its own.
Applies to mod_outputs; serves goal_extensible; evidenced by t_renderer_backend

A mode that reads input is registered twice: in the mode table, and with the reader for its format. Readers and writers vary independently; most reading modes share one writer. Consequence: A reading mode registered only once parses its input as SBDL and produces wrong output rather than an error.
Applies to cmp_mode_table; evidenced by t_mode_aliases

Diagram modes come from a selected rendering backend, so one mode name dispatches to a different writer per backend. Lets the native renderer replace PlantUML behind unchanged command lines, and an unknown backend fails rather than drawing nothing.
Applies to cmp_mode_table; serves goal_stable_cli, goal_dependency_light; evidenced by t_renderer_backend

A service that needs the writers receives the mode table as an argument instead of importing it. Keeps services such as the MCP server below the entry in the import graph and free of mode-specific code.
Applies to mod_mcp; serves goal_extensible; evidenced by t_mcp_server

Outputs project the model; they never restate it or invent what it does not say. A diagram that asserts something absent from the model is worse than one that leaves it out, as with an inferred initial state.
Applies to lyr_writers

Rendering

Anything measured and then drawn is computed by one function used for both. Separate copies drift: labels were sized at one position and painted at another, and clipped.
Applies to mod_native_svg

A style pack changes paint and spacing only, never shape, notation or layout. Every machine-readable hook in the SVG stays identical across styles, which the editor and the tests rely on.
Applies to cmp_theme

Every drawn element carries data-sbdl attributes naming the model element it shows. Tests count hooks instead of geometry, so they survive layout changes, and the editor makes diagrams clickable.
Applies to mod_native_sysml; evidenced by t_native_renderer

PNG output pipes SVG through an external command rather than a Python binding. Bindings are C extensions that break PyPy; a missing rasteriser fails loudly instead of writing SVG into a file named png.
Applies to mod_native_svg; serves goal_portable, goal_dependency_light

Quality

Sets are never iterated on an output path without sorting. String set order varies per process under hash randomisation, so it silently became property order in several writers.
Applies to sbdl_compiler; serves goal_reproducible

Layouts use only correctly rounded operations and a summation that is identical on every interpreter. A layout is a feedback loop: one bit of difference in a sum steers every later iteration.
Applies to cmp_layouts; serves goal_reproducible, goal_portable; evidenced by t_native_renderer

Tests drive the real command line or protocol wherever the wiring is part of the behaviour. Flag wiring, configuration loading and mode registration are exactly what an in-process call skips.
Applies to mod_tests

The suite runs against the minified distribution before a release, not only against the source. Some defects exist only in the minified form, where a renamed name meets an interpreter optimisation.
Applies to mod_build; serves goal_correct_build; evidenced by t_distribution

Compliance compares meaning, not text: both outputs are recompiled by the reference and the canonical forms compared. compile is idempotent, so formatting differences dissolve and only changes of meaning remain.
Applies to mod_compliance; serves goal_qualifiable; evidenced by t_compliance_self

Every compliance case states its expected outcome, and a case the reference disagrees with blames the corpus. A deliberate change of behaviour then surfaces as a corpus disagreement instead of silent drift.
Applies to mod_compliance; serves goal_qualifiable; evidenced by t_compliance_self

Operations

Standard output carries only the requested output; everything for humans goes to standard error. The default output is stdout, and the language and MCP servers speak their protocols over it.
Applies to cmp_printing; evidenced by t_mcp_server

The compiler never waits for an answer that nobody can give. An install prompt inside CI or a captured child process blocks forever and invisibly.
Applies to cmp_lazy_import

Compiling and building model snapshots happen on worker threads, never on the language server event loop. A request waiting on a compile delays every request behind it, including shutdown.
Applies to cmp_doc_worker; serves goal_responsive_editor; evidenced by t_lsp_smoke

The public repository receives one dated commit per release, built from a manifest of the private one. Working history and timestamps stay private; a new file stays private until listed.
Applies to mod_public_release

Boundaries

Protocols

A wire or file format through which other programs drive or consume the compiler.

Extension Points

A seam through which the compiler is extended without editing it.

External Software

Software outside the compiler that it calls, or that calls it.

Behaviour

Use Cases

Functions

fn_compile_run

One compilation: configuration, reading, parsing, model construction, filtering, verification and the mode. Defined at sbdl.py:117, owned by mod_entry.

Input: Source files, a mode and options. Output: The mode’s artefact, and the total error count as exit status. Invariant: Every stage ends at check_step.

fn_lsp_document

The life of one open document in the language server. Defined at compiler_design.sbdl:472, owned by mod_lsp.

Input: Document notifications from the editor. Output: Diagnostics, symbols and model snapshots.

fn_mcp_call

One MCP tool call against the model compiled at start-up. Defined at sbdl_mcp.py:35, owned by mod_mcp.

Input: A JSON-RPC request. Output: Text or image content.

fn_batch

Run the jobs declared by BATCH directives against the one compiled model. Defined at sbdl_outputs.py:1709, owned by cmp_batch.

Output: One artefact per job.

fn_trace_verify

Replay trace elements against the statically defined behaviour. Defined at sbdl_outputs.py:2017, owned by cmp_model_machine.

Input: A model and the trace elements found in logs. Output: A verdict per step, as prose or JSON.

fn_compliance

Qualify a candidate compiler against the reference. Defined at compiler_design.sbdl:498, owned by mod_compliance.

Input: A candidate command line. Output: A per-profile verdict with its scope of claim.

fn_release

Build, test and publish a release. Defined at compiler_design.sbdl:521, owned by mod_build.

Output: A distribution and one public commit.

fn_native_render

How every native diagram mode draws. Defined at compiler_design.sbdl:534, owned by mod_native_sysml.

Input: The AST and the resolved diagram roots. Output: SVG, or PNG through an external rasteriser.

Other Events

State Machines

Design Hazards

A way the design is known to be broken by a plausible change.

Evidence