surfaces.sysml

// What sits on top of the pipeline: the interactive surfaces, the client
// libraries that reach the service, and the artifacts the tool writes out.
package OpenSysMLSurfaces {
    private import ScalarValues::*;
    private import OpenSysMLArtifacts::*;
    private import OpenSysMLPipeline::*;

    abstract part def Interface :> CodeUnit {
        attribute entrypoint : String;
        attribute protocol : String;
        port pipeline : RequestPort;
    }

    // A surface that asks questions of the model puts every one through the
    // analysis framework, choosing the engines and the width of the fleet.
    abstract part def AskingInterface :> Interface {
        attribute engineSelector : String;
        attribute jobsSetting : String;
        attribute engineListing : String;
        port questions : RequestPort;
    }

    #Surface part def Repl :> AskingInterface {
        attribute :>> goPackage = "internal/frontend/repl";
        attribute :>> entrypoint = "cmd/sysml";
        attribute :>> protocol = "terminal";
        attribute :>> engineSelector = "%engine";
        attribute :>> jobsSetting = "%jobs";
        attribute :>> engineListing = "%engines";
        attribute stateful : Boolean = true;
        attribute adoptsInstancesOnReanalysis : Boolean = true;
    }

    // Every capability the server announces in its initialize result. The
    // standard ones are the protocol's; the experimental ones are the extension
    // the VS Code client speaks: rendering a view or a document, applying a
    // model edit, reading a bundled library file, debugging a run, laying a
    // diagram out across documents, and the palette, forms and styles it draws with.
    #Surface part def LanguageServer :> Interface {
        attribute :>> goPackage = "internal/frontend/lsp";
        attribute :>> entrypoint = "cmd/sysml-lsp";
        attribute :>> protocol = "lsp-stdio";
        attribute incrementalSync : Boolean = true;
        attribute saveNotifications : Boolean = true;
        attribute workspaceFolders : Boolean = true;
        attribute publishesQuickFixes : Boolean = true;
        attribute identityCodeActions : Boolean = true;
        attribute hover : Boolean = true;
        attribute definition : Boolean = true;
        attribute findReferences : Boolean = true;
        attribute documentSymbols : Boolean = true;
        attribute workspaceSymbols : Boolean = true;
        attribute completion : Boolean = true;
        attribute formatting : Boolean = true;
        attribute rangeFormatting : Boolean = true;
        attribute rename : Boolean = true;
        attribute prepareRename : Boolean = true;
        attribute semanticTokens : Boolean = true;
        attribute experimentalRendering : Boolean = true;
        attribute experimentalDocuments : Boolean = true;
        attribute experimentalModelEdits : Boolean = true;
        attribute experimentalStdlibContent : Boolean = true;
        attribute experimentalDebug : Boolean = true;
        attribute experimentalCrossDocumentLayout : Boolean = true;
        attribute experimentalRenderPalette : Boolean = true;
        attribute experimentalRenderForms : Boolean = true;
        attribute experimentalRenderStyles : Boolean = true;
        attribute notebookCells : Boolean = true;
        attribute notebookCellLanguages : String = "sysml, kerml";
        attribute settingsSection : String = "sysml";
        attribute keepLineBreaksSetting : String = "keepLineBreaks";
        attribute keepLineBreaksFlag : String = "-keep-line-breaks";
        attribute strictFlag : String = "-strict";
        attribute libraryRootsSetting : String = "libraryRoots";
        attribute importDiagramMethod : String = "opensysml/importDiagram";
        in item findings : Diagnostic;
        out item tokens : SemanticToken;
        out item fixes : QuickFix;
    }

    // The schema every transport and every client is generated from. Only the
    // Go stubs are checked in beside it; the other stubs live with their clients.
    part def ApiSchema :> CodeUnit {
        attribute :>> goPackage = "api/proto";
        attribute schemaFile : String = "api/proto/sysml.proto";
        attribute service : String = "SysMLService";
        attribute rpcCount : Integer = 33;
        attribute rpcs : String = "GetServerInfo, ParseFile, ParseSources, GetSymbol, GetDiagnostics, Evaluate, Instantiate, InstancePaths, ExecuteAction, ExecuteState, Convert, Migrate, ApplyEdits, VerifyConstraint, VerifyRequirement, VerifySatisfaction, ValidateInstance, EvaluateCalc, RunAnalysis, CheckBehavior, RunSweep, RunRuns, SelfCheck, RecordRun, ListEngines, Query, GetElementProperties, RunDocumentQuery, RenderDocument, RenderView, ExportGraphs, ImportData, CompareResults";
        attribute generatedGo : String = "api/proto/sysml.pb.go, api/proto/sysml_grpc.pb.go, api/proto/protoconnect/sysml.connect.go";
        attribute generator : String = "buf";
    }

    // One hand-written service behind two generated transports: gRPC over
    // HTTP/2 with reflection, and Connect over plain HTTP for browsers.
    #Surface part def ModelService :> AskingInterface {
        attribute :>> goPackage = "internal/frontend/grpc";
        attribute :>> entrypoint = "cmd/sysml-grpc";
        attribute :>> protocol = "grpc, connect";
        attribute :>> engineSelector = "engine";
        attribute :>> jobsSetting = "OPENSYSML_JOBS";
        attribute :>> engineListing = "ListEngines";
        attribute enginesCapability : String = "engines";
        attribute reflectionEnabled : Boolean = true;
        attribute handWrittenService : Boolean = true;
        attribute connectAdapter : String = "internal/frontend/grpc/connect.go";
        attribute stdioTransport : String = "internal/frontend/stdiorpc";
        attribute hostSetting : String = "-host";
        attribute loopbackByDefault : Boolean = true;
        attribute tokenSettings : String = "-token, -token-file";
        attribute bearerTokenEnv : String = "OPENSYSML_GRPC_TOKEN";
        attribute unauthenticatedSetting : String = "-allow-unauthenticated";
        attribute insecureTokenSetting : String = "-allow-insecure-token-transport";
        attribute accessControl : String = "cmd/sysml-grpc/access.go";
        attribute logsEveryCall : Boolean = true;
        part schema : ApiSchema;
    }

    // The same service over a pipe: a process that embeds the binary talks to
    // it without a network listener.
    #Surface part def StdioService :> Interface {
        attribute :>> goPackage = "internal/frontend/stdiorpc";
        attribute :>> entrypoint = "cmd/sysml-grpc";
        attribute :>> protocol = "stdio";
    }

    // The non-interactive side of the REPL binary: convert, migrate, query, render.
    #Surface part def CommandLine :> AskingInterface {
        attribute :>> goPackage = "internal/frontend/repl";
        attribute :>> entrypoint = "cmd/sysml";
        attribute :>> protocol = "flags";
        attribute :>> engineSelector = "-engine";
        attribute :>> jobsSetting = "-jobs";
        attribute :>> engineListing = "-engines";
        attribute exitStatusIsContract : Boolean = true;
        attribute reportSetting : String = "-format";
        attribute reportFormats : String = "text, json, sarif, junit";
        attribute reportPackages : String = "internal/frontend/report";
        attribute verbs : String = "-convert, -migrate, -compile, -render, -render-all, -render-document, -render-documents, -graphs, -metaclass-graph, -metamodel-table, -run-query, -run-inline-query, -list, -sync-diff, -sync-apply, -import-diagram";
        attribute importDiagramSetting : String = "-import-diagram";
    }

    // Coding agents reach the toolchain over the Model Context Protocol: one
    // server over a workspace root, its tools in three groups — the language
    // server's, the one-shot service's and named REPL sessions — over stdio
    // or Streamable HTTP behind a bearer token.
    #Surface part def McpServer :> Interface {
        attribute :>> goPackage = "internal/frontend/mcp";
        attribute :>> entrypoint = "cmd/sysml-mcp";
        attribute :>> protocol = "mcp-stdio, mcp-http";
        attribute toolCatalog : String = "internal/frontend/mcp/catalog";
        attribute toolGroups : String = "lsp, runtime, session";
        attribute groupSelector : String = "-tools";
        attribute httpSetting : String = "-http";
        attribute httpPath : String = "/mcp";
        attribute tokenEnv : String = "OPENSYSML_MCP_TOKEN";
        attribute conformanceTarget : String = "conformance-mcp";
        attribute registryManifest : String = "packaging/mcp/server.json";
        attribute importDiagramTool : String = "import_diagram";
    }

    // A notebook kernel over the REPL: the Jupyter wire protocol on ZeroMQ
    // sockets, each answer shown in its own MIME form beside plain text.
    #Surface part def JupyterKernel :> Interface {
        attribute :>> goPackage = "internal/frontend/jupyter";
        attribute :>> entrypoint = "cmd/sysml-jupyter-kernel";
        attribute :>> protocol = "jupyter-zmq";
        attribute kernelName : String = "sysml";
        attribute displayName : String = "SysML v2 (OpenSysML)";
        attribute connectionSetting : String = "-connection-file";
        attribute installSetting : String = "-install";
        attribute mimeTypes : String = "text/plain, text/markdown, text/html, text/vnd.mermaid, text/vnd.graphviz, image/svg+xml, text/csv, text/tab-separated-values, application/json";
        attribute wrapsRepl : Boolean = true;
        port repl : RequestPort;
    }

    // The commands a WebAssembly host runs: protojson bodies in JSON-RPC 2.0
    // frames on stdio, or a call on a JavaScript global, each serving the slice
    // of the service's RPCs named in serves without the networking packages.
    abstract part def JsonCommand :> Interface {
        attribute :>> protocol = "json-rpc";
        attribute jsonTransport : String = "internal/frontend/jsonrpc";
        attribute serves : String;
        attribute released : Boolean default = false;
        attribute buildsForWasm : Boolean = true;
    }

    // Stateless and without a standard library: syntax alone.
    #Surface part def SyntaxCommand :> JsonCommand {
        attribute :>> goPackage = "internal/frontend/syntax";
        attribute :>> entrypoint = "cmd/sysml-syntax";
        attribute :>> serves = "Parse, Format, Tokens";
        attribute stateless : Boolean = true;
    }

    #Surface part def EngineCommand :> JsonCommand {
        attribute :>> goPackage = "internal/frontend/engine";
        attribute :>> entrypoint = "cmd/sysml-engine";
        attribute :>> serves = "ParseSources, Evaluate, Instantiate, ExecuteAction, ExecuteState, RenderView, RenderDocument";
    }

    #Surface part def CoreCommand :> JsonCommand {
        attribute :>> goPackage = "internal/frontend/core";
        attribute :>> entrypoint = "cmd/sysml-core";
        attribute :>> serves = "ParseSources, ParseFile, GetDiagnostics, GetSymbol";
    }

    // Not a released command, but a release ships its browser build as an asset.
    #Surface part def CombinedCommand :> JsonCommand {
        attribute :>> goPackage = "internal/frontend/combined";
        attribute :>> entrypoint = "cmd/sysml-wasm";
        attribute :>> serves = "ParseSources, ParseFile, GetDiagnostics, GetSymbol, Evaluate, Instantiate, ExecuteAction, ExecuteState, RenderView, RenderDocument, GetServerInfo";
        attribute releaseAsset : String = "sysml-wasm.wasm";
    }

    // A client library: hand-written idiomatic code over stubs generated from
    // the schema, checked in at generatedStubs or generated by the build that
    // generatedStubs names — or, where no protobuf toolchain is at hand, JSON
    // over HTTP against the Connect-JSON surface, decoded by the rules of
    // docs/reference/wire-contract.md.
    abstract part def Client :> CodeUnit {
        attribute implementationLanguage : String;
        attribute generatedFrom : String = "api/proto";
        attribute generatedStubs : String;
        attribute generatedCode : Boolean default = true;
        attribute connectionCode : String;
        attribute tokenOption : String;
        attribute bearerTokenEnv : String = "OPENSYSML_GRPC_TOKEN";
        port service : RequestPort;
    }

    part def PythonClient :> Client {
        attribute :>> goPackage = "client/python";
        attribute :>> implementationLanguage = "python";
        attribute :>> generatedStubs = "client/python/opensysml/proto";
        attribute :>> connectionCode = "client/python/opensysml/connection.py";
        attribute :>> tokenOption = "token";
    }

    part def NodeClient :> Client {
        attribute :>> goPackage = "client/node";
        attribute :>> implementationLanguage = "typescript";
        attribute :>> generatedStubs = "client/node/src/generated";
        attribute :>> connectionCode = "client/node/src/node/service.ts";
        attribute :>> tokenOption = "token";
    }

    part def RustClient :> Client {
        attribute :>> goPackage = "client/rust";
        attribute :>> implementationLanguage = "rust";
        attribute :>> generatedStubs = "client/rust/opensysml/src/proto";
        attribute :>> connectionCode = "client/rust/opensysml/src/connection.rs";
        attribute :>> tokenOption = "token";
    }

    part def JavaClient :> Client {
        attribute :>> goPackage = "client/java";
        attribute :>> implementationLanguage = "java";
        // The Maven build generates the message classes under target/.
        attribute :>> generatedStubs = "client/java/opensysml-client/pom.xml";
        attribute :>> connectionCode = "client/java/opensysml-client/src/main/java/org/openmbee/opensysml/ConnectionOptions.java";
        attribute :>> tokenOption = "token";
    }

    part def JuliaClient :> Client {
        attribute :>> goPackage = "client/julia";
        attribute :>> implementationLanguage = "julia";
        attribute :>> generatedStubs = "docs/reference/wire-contract.md";
        attribute :>> generatedCode = false;
        attribute :>> connectionCode = "client/julia/OpenSysML/src/connection.jl";
        attribute :>> tokenOption = "token";
    }

    // Runs in MATLAB and in GNU Octave.
    part def MatlabClient :> Client {
        attribute :>> goPackage = "client/matlab";
        attribute :>> implementationLanguage = "matlab";
        attribute :>> generatedStubs = "docs/reference/wire-contract.md";
        attribute :>> generatedCode = false;
        attribute :>> connectionCode = "client/matlab/+opensysml/external.m";
        attribute :>> tokenOption = "token";
    }

    // In the same process by default, over the wire on request: the Go client
    // wraps the generated Go stubs rather than being generated itself, and
    // every command builds for WebAssembly as well as natively.
    part def GoClient :> Client {
        attribute :>> goPackage = "client/opensysml";
        attribute :>> implementationLanguage = "go";
        attribute :>> generatedStubs = "api/proto";
        attribute :>> connectionCode = "client/opensysml/remote.go";
        attribute :>> tokenOption = "WithToken";
        attribute inProcess : Boolean = true;
        attribute buildsForWasm : Boolean = true;
    }

    // The language client, the diagram panel it draws in a webview, the
    // landing page, and the TextMate grammars a generator writes from the
    // keyword lists — the same run writes the JupyterLab syntax table.
    part def VsCodeExtension :> CodeUnit {
        attribute :>> goPackage = "editors/vscode";
        attribute speaksTo : String = "sysml-lsp";
        attribute languages : String = "sysml, kerml";
        attribute commands : String = "opensysml.restartServer, opensysml.openDiagram, opensysml.exportDiagram, opensysml.importDiagram, opensysml.diagram.popOut, opensysml.renderDocument, opensysml.runElement";
        attribute diagramPanel : String = "editors/vscode/src/webview";
        attribute landingPage : String = "editors/vscode/src/landing";
        attribute grammarGenerator : String = "editors/vscode/tools/gengrammar";
        attribute grammarTarget : String = "vscode-grammar";
        port languageClient : RequestPort;
    }

    // The Emacs package: a major mode over keyword lists a generator writes
    // from the lexer, an lsp-mode client and a diagram buffer, under ERT.
    part def EmacsMode :> CodeUnit {
        attribute :>> goPackage = "editors/emacs";
        attribute speaksTo : String = "sysml-lsp";
        attribute languages : String = "sysml, kerml";
        attribute lispFiles : String = "sysml-mode.el, sysml-lsp.el, sysml-diagram.el";
        attribute lspClient : String = "lsp-mode";
        attribute keywordTable : String = "editors/emacs/sysml-mode-keywords.el";
        attribute keywordGenerator : String = "editors/emacs/tools/genkeywords";
        attribute keywordTarget : String = "emacs-keywords";
        attribute compileTarget : String = "emacs-compile";
        attribute testTarget : String = "emacs-test";
        port languageClient : RequestPort;
    }

    // Helix, Neovim and Zed highlight through Tree-sitter grammars kept in a
    // sibling repository; the editors' guide wires each to the language server.
    part def TreeSitterGrammars {
        attribute repository : String = "https://github.com/Open-MBEE/tree-sitter-sysml";
        attribute editors : String = "Helix, Neovim, Zed";
        attribute guide : String = "docs/guide/08-editors.md";
        attribute speaksTo : String = "sysml-lsp";
    }

    // A modelling tool reaching the service through the Java client — Magic MDK
    // as a Cameo plugin, SysON MDK as a SysON backend; each pom names the plugin.
    abstract part def ToolIntegration :> CodeUnit {
        attribute speaksTo : String = "sysml-grpc";
        attribute overClient : String = "client/java";
        attribute pluginName : String;
        attribute groupId : String = "org.openmbee";
        attribute artifactId : String;
        port serviceClient : RequestPort;
    }

    part def MagicMDK :> ToolIntegration {
        attribute :>> goPackage = "editors/mdk";
        attribute :>> pluginName = "Magic MDK";
        attribute :>> artifactId = "magic-mdk-parent";
        attribute javaPackage : String = "org.openmbee.mdk.magic";
    }

    part def SysonMDK :> ToolIntegration {
        attribute :>> goPackage = "editors/syson";
        attribute :>> pluginName = "SysON MDK";
        attribute :>> artifactId = "syson-mdk";
    }

    // The kernel as a pip package: the binary and the JupyterLab extension
    // in one wheel, registered as a kernelspec; no service is involved.
    part def JupyterKernelPackage :> CodeUnit {
        attribute :>> goPackage = "client/jupyter-kernel";
        attribute implementationLanguage : String = "python";
        attribute packageName : String = "jupyter-opensysml-kernel";
        attribute installTarget : String = "jupyter-kernel-install";
        attribute testTarget : String = "jupyter-kernel-test";
        port kernel : RequestPort;
    }

    // Highlighting for the notebook: a CodeMirror language over the syntax
    // table the grammar generator writes, built into the kernel package.
    part def JupyterLabExtension :> CodeUnit {
        attribute :>> goPackage = "editors/jupyterlab";
        attribute packageName : String = "jupyterlab-opensysml";
        attribute syntaxTable : String = "editors/jupyterlab/src/syntax.json";
        attribute buildTarget : String = "jupyterlab-build";
        attribute testTarget : String = "jupyterlab-test";
        port notebook : RequestPort;
    }

    // The MCP server as an npm package: a runner that fetches the released
    // binary for its platform, published under two names.
    part def McpNpmPackage :> CodeUnit {
        attribute :>> goPackage = "packaging/npm/sysml-mcp";
        attribute packageName : String = "@openmbee/sysml-mcp";
        attribute npmAlias : String = "@openmbee/opensysml-mcp";
        attribute coverageTarget : String = "mcp-npm-coverage";
        port server : RequestPort;
    }

    // What every surface finds beside a model: the package manager's project
    // file, the well-known library directories and the override variable.
    part def ProjectDiscovery :> CodeUnit {
        attribute :>> goPackage = "internal/workspace/project";
        attribute projectFile : String = ".project.json";
        attribute wellKnownLibraryDirs : String = "lib, .sysand/lib";
        attribute libraryRootsEnv : String = "OPENSYSML_LIBRARY_ROOTS";
    }

    // --- What an editor reaches ------------------------------------------

    // Semantic-token classes, in the order the LSP legend lists them.
    part def Highlighter :> CodeUnit {
        attribute :>> goPackage = "internal/semantic/highlight";
        attribute tokenClasses : Integer = 15;
        in item tree : SyntaxTree;
        out item tokens : SemanticToken;
    }

    // A fix carries the edit that applies it and points at the diagnostic it
    // answers; a diagnostic with no unambiguous repair offers none.
    part def QuickFixer :> CodeUnit {
        attribute :>> goPackage = "internal/syntax/diag";
        attribute editsAttached : Boolean = true;
        in item findings : Diagnostic;
        out item fixes : QuickFix;
    }

    // The nearest declared names for one that did not resolve.
    part def Suggester :> CodeUnit {
        attribute :>> goPackage = "internal/semantic/suggest";
        attribute rankedByDistance : Boolean = true;
        in item findings : Diagnostic;
    }

    // Span-based rewriting of source text. The result is re-parsed and
    // re-analysed, and an edit that would leave the model unreadable is refused.
    part def SourceEditor :> CodeUnit {
        attribute :>> goPackage = "internal/check/edit";
        attribute operations : String = "set value, rename, add member, delete, add connection, move, set layout, add satisfy, add requirement constraint, add transition, add verify, add metadata, add metadata prefix, add sequence, add import, add documentation, add comment, add note";
        attribute preservesUntouchedText : Boolean = true;
        attribute reanalysesResult : Boolean = true;
        in item text : SourceText;
        out item edits : SourceEdit;
    }

    // Re-indents the token stream, so comments and error nodes survive a save.
    part def Formatter :> CodeUnit {
        attribute :>> goPackage = "internal/syntax/format";
        attribute worksOnTokens : Boolean = true;
        in item text : SourceText;
    }

    // A document name and a span, carried from a declaration to whatever is
    // derived from it; a synthetic artifact carries the unlocated origin.
    part def Provenance :> CodeUnit {
        attribute :>> goPackage = "internal/semantic/symbols";
        attribute keyedByDocumentAndSpan : Boolean = true;
        attribute consumers : String = "internal/doc/docir, internal/ir/view, internal/ir/queryplan";
        out item origins : SourceSpan;
    }

    // Diagnostics feed fixes and suggestions; edits go back in as source text.
    part def EditorPipeline {
        part highlighter : Highlighter;
        part fixes : QuickFixer;
        part suggestions : Suggester;
        part editor : SourceEditor;
        part formatter : Formatter;

        port findingsIn : DiagnosticPort;
        port textOut : ArtifactPort;

        flow of Diagnostic from fixes.findings to suggestions.findings;
        flow of SourceEdit from editor.edits to formatter.text;
    }

    // --- What the tool writes out ----------------------------------------

    // A rendering kind the standard view definitions name.
    part def RenderingKind {
        attribute kind : String;
        attribute supported : Boolean default = true;
    }

    // A rendering form: the notation a rendering is written in; diagram forms
    // feed -diagram-form, run-only ones render runs, editable ones import back.
    part def RenderingForm {
        attribute form : String;
        attribute diagram : Boolean default = false;
        attribute runOnly : Boolean default = false;
        attribute editable : Boolean default = false;
    }

    // Every rendering form the view package writes, held apart from the
    // engine's kinds so each is a table of its own.
    part def RenderingForms :> CodeUnit {
        attribute :>> goPackage = "internal/ir/view";
        attribute formCount : Integer = 11;
        attribute viewFormCount : Integer = 9;
        part textForm : RenderingForm { attribute :>> form = "text"; }
        part mermaidForm : RenderingForm { attribute :>> form = "mermaid"; attribute :>> diagram = true; }
        part markdownForm : RenderingForm { attribute :>> form = "markdown"; }
        part dotForm : RenderingForm { attribute :>> form = "dot"; attribute :>> diagram = true; }
        part plantumlForm : RenderingForm { attribute :>> form = "plantuml"; attribute :>> diagram = true; }
        part d2Form : RenderingForm { attribute :>> form = "d2"; attribute :>> diagram = true; }
        part drawioForm : RenderingForm { attribute :>> form = "drawio"; attribute :>> editable = true; }
        part csvForm : RenderingForm { attribute :>> form = "csv"; }
        part tsvForm : RenderingForm { attribute :>> form = "tsv"; }
        part svgForm : RenderingForm { attribute :>> form = "svg"; attribute :>> runOnly = true; }
        part svgAnimatedForm : RenderingForm { attribute :>> form = "svg-animated"; attribute :>> runOnly = true; }
    }

    // Every rendering kind the implementation recognizes is modelled here.
    part def ViewEngine :> CodeUnit {
        attribute :>> goPackage = "internal/ir/view";
        attribute recognizedKinds : Integer = 14;
        attribute supportedKinds : Integer = 12;
        part tree : RenderingKind { attribute :>> kind = "tree"; }
        part interconnection : RenderingKind { attribute :>> kind = "interconnection"; }
        part stateDiagram : RenderingKind { attribute :>> kind = "state"; }
        part actionDiagram : RenderingKind { attribute :>> kind = "action"; }
        part textual : RenderingKind {
            attribute :>> kind = "textual";
            attribute :>> supported = false;
        }
        part table : RenderingKind { attribute :>> kind = "table"; }
        part matrix : RenderingKind { attribute :>> kind = "matrix"; }
        part sequence : RenderingKind { attribute :>> kind = "sequence"; }
        part caseDiagram : RenderingKind { attribute :>> kind = "case"; }
        part mixedDiagram : RenderingKind { attribute :>> kind = "mixed"; }
        part requirementGraph : RenderingKind { attribute :>> kind = "requirement"; }
        part definitionGraph : RenderingKind { attribute :>> kind = "definition"; }
        part packageGraph : RenderingKind { attribute :>> kind = "package"; }
        part geometry : RenderingKind {
            attribute :>> kind = "geometry";
            attribute :>> supported = false;
        }
        in item types : TypeTable;
        in item origins : SourceSpan;
        out item diagram : DocumentTree;
    }

    part def QueryCompiler :> CodeUnit {
        attribute :>> goPackage = "internal/ir/queryplan";
        attribute immutablePlans : Boolean = true;
    }

    part def QueryExecutor :> CodeUnit {
        attribute :>> goPackage = "internal/doc/queryexec";
        attribute orderedRows : Boolean = true;
        out item rows : QueryRows;
    }

    // A document is written in the notation, not in a template language: the
    // planner compiles a document definition into an immutable plan holding
    // compiled query programs.
    part def DocumentPlanner :> CodeUnit {
        attribute :>> goPackage = "internal/ir/docplan";
        attribute libraryFile : String =
            "internal/workspace/libs/stdlib/OpenSysML Libraries/DocumentQueries.sysml";
        attribute immutablePlans : Boolean = true;
        attribute contentKinds : String = "section, paragraph, table, list, definitions, formula, diagram, image";
        attribute runKinds : String = "span, link, ref";
        attribute markupLanguages : String = "markdown, asciidoc";
        in item rows : QueryRows;
        in item prose : ProseBlocks;
        out item plan : DocumentPlan;
    }

    // A prose body written in a markup language is parsed into the planner's
    // blocks; Markdown here, AsciiDoc by Asciidoctor.js outside the process.
    abstract part def MarkupParser :> CodeUnit {
        attribute :>> goPackage = "internal/ir/docplan/markup";
        attribute markupLanguage : String;
        attribute needsExternalTool : Boolean default = false;
        out item blocks : ProseBlocks;
    }

    part def MarkdownParser :> MarkupParser {
        attribute :>> markupLanguage = "markdown";
    }

    part def AsciiDocParser :> MarkupParser {
        attribute :>> markupLanguage = "asciidoc";
        attribute :>> needsExternalTool = true;
        attribute toolEnv : String = "OPENSYSML_ASCIIDOCTOR";
        attribute converterScript : String = "scripts/asciidoc/asciidoctor-json.js";
    }

    // Evaluating a plan gives one tree, carrying provenance on every node and
    // knowing nothing about the backend that will write it out.
    part def DocumentIR :> CodeUnit {
        attribute :>> goPackage = "internal/doc/docir";
        attribute backendAgnostic : Boolean = true;
        attribute provenancePerNode : Boolean = true;
        attribute resolvesCrossDocumentRefs : Boolean = true;
        in item plan : DocumentPlan;
        in item origins : SourceSpan;
        out item tree : DocumentTree;
    }

    part def MarkdownBackend :> CodeUnit {
        attribute :>> goPackage = "internal/doc/docrender";
        attribute form : String = "markdown";
        attribute needsExternalTool : Boolean = false;
        in item tree : DocumentTree;
    }

    // One self-contained page with the stylesheet in it; its diagrams are
    // Mermaid sources a script the page loads draws, so nothing runs here.
    part def HtmlBackend :> CodeUnit {
        attribute :>> goPackage = "internal/doc/docrender";
        attribute form : String = "html";
        attribute needsExternalTool : Boolean = false;
        attribute diagramsDrawnByPage : Boolean = true;
        in item tree : DocumentTree;
    }

    // The only stage that leaves the process: the tree becomes prepared
    // Markdown, its diagrams become images, and a converter makes the PDF.
    part def PdfBackend :> CodeUnit {
        attribute :>> goPackage = "internal/doc/docpdf";
        attribute form : String = "pdf";
        attribute engines : String = "weasyprint, pandoc, prince";
        attribute diagramTool : String = "mmdc";
        attribute needsExternalTool : Boolean = true;
        attribute reportsMissingTool : Boolean = true;
        in item tree : DocumentTree;
    }

    // A SysML v1 model read from XMI — as Eclipse UML2 writes it or in a mdzip
    // archive — and written as SysML v2 notation under its own verb, migrated
    // rather than converted, with what each v1 element became reported; an
    // MTIP export lays the migrated views out, and a results sidecar lets a
    // migrated run configuration be compared with the runs its tool stored.
    part def Migrator :> CodeUnit {
        attribute :>> goPackage = "internal/translate/migrate";
        attribute reader : String = "internal/translate/xmi/sysmlv1";
        attribute layoutSource : String = "internal/translate/mtip";
        attribute resultsSchema : String = "internal/exec/simresults";
        attribute verb : String = "-migrate";
        attribute rpc : String = "Migrate";
        attribute reportFlag : String = "-migration-report";
        attribute resultsFlag : String = "-migration-results";
        attribute layoutFlag : String = "-layout";
        attribute comparisonFlag : String = "-compare-results";
        attribute reportsEveryElement : Boolean = true;
    }

    // A calc def compiled to a native source file rather than interpreted;
    // notation outside the compiled subset is named, never silently interpreted.
    part def CodeGenerator :> CodeUnit {
        attribute :>> goPackage = "internal/translate/codegen";
        attribute targets : String = "c, go";
        attribute flag : String = "-compile";
        attribute namesUnsupportedNotation : Boolean = true;
    }

    // Textual notation both ways, the experimental RDF and API element form,
    // SysML v1 XMI read and migrated, and FMI model descriptions imported as
    // calc defs. Five formats, twelve names: kerml and text are the notation,
    // turtle and rdf are Turtle, api-json and json are the API's element form,
    // uml is XMI as Eclipse UML2 writes it, mdzip is XMI in a zip archive and
    // fmu is an FMI package.
    part def Exporter :> CodeUnit {
        attribute :>> goPackage = "internal/translate/export";
        attribute formats : String = "api-json, fmu, sysml, ttl, xmi";
        attribute formatNames : String = "api-json, fmu, json, kerml, mdzip, rdf, sysml, text, ttl, turtle, uml, xmi";
        attribute roundTrips : Boolean = true;
        out item graph : RdfGraph;
    }

    part def OslcQuery :> CodeUnit {
        attribute :>> goPackage = "internal/semantic/query";
        attribute dialect : String = "oslc";
    }

    // The document path, from a query in the model to a rendered artifact.
    // One plan, one tree, three backends: the form is chosen at the end, so
    // Markdown, HTML and PDF cannot disagree about the document's content.
    part def DocumentPipeline {
        part provenance : Provenance;
        part views : ViewEngine;
        part queries : QueryCompiler;
        part rows : QueryExecutor;
        part plans : DocumentPlanner;
        part markdownProse : MarkdownParser;
        part asciidocProse : AsciiDocParser;
        part ir : DocumentIR;
        part markdown : MarkdownBackend;
        part html : HtmlBackend;
        part pdf : PdfBackend;

        port modelIn : ArtifactPort;
        port artifactOut : ArtifactPort;

        flow of SourceSpan from provenance.origins to views.origins;
        flow of SourceSpan from provenance.origins to ir.origins;
        flow of QueryRows from rows.rows to plans.rows;
        flow of ProseBlocks from markdownProse.blocks to plans.prose;
        flow of ProseBlocks from asciidocProse.blocks to plans.prose;
        flow of DocumentPlan from plans.plan to ir.plan;
        flow of DocumentTree from ir.tree to markdown.tree;
        flow of DocumentTree from ir.tree to html.tree;
        flow of DocumentTree from ir.tree to pdf.tree;
        flow of DocumentTree from views.diagram to pdf.tree;
    }

    // One document rendered, and the one branch in it: the form.
    action def RenderDocument {
        attribute form : String = "markdown";
        attribute toolsPresent : Boolean = true;

        in item model : SourceText;
        out item artifact : DocumentTree;

        first start;

        action runQueries;
        action compilePlan;
        action evaluatePlan;
        action writeMarkdown;
        action writeHtml;
        action renderDiagrams;
        action convertPdf;
        action reportMissingTool;

        succession first start then runQueries;
        succession first runQueries then compilePlan;
        succession first compilePlan then evaluatePlan;
        succession first evaluatePlan then formGate;

        decide formGate;
        if form == "markdown" then writeMarkdown;
        if form == "html" then writeHtml;
        else renderDiagrams;

        // A missing converter is reported, never a half-written document.
        succession first renderDiagrams then toolGate;

        decide toolGate;
        if toolsPresent then convertPdf;
        else reportMissingTool;
    }

    requirement def DocumentsCarryTheirProvenance {
        doc /* Every rendered node can be traced back to the element it came from,
             * and both backends read the same tree. */
        subject documents : DocumentPipeline;
        require constraint {
            documents.ir.provenancePerNode and documents.ir.backendAgnostic
                and documents.plans.immutablePlans
        }
    }

    // --- Conformance oracles ---------------------------------------------

    // Harnesses that referee this implementation against a reference; each
    // holds a committed baseline that must move deliberately. An advisory
    // oracle reports drift; a gating one fails the build on it.
    abstract part def ConformanceOracle :> CodeUnit {
        attribute reference : String;
        attribute baseline : String;
        attribute gating : Boolean default = false;
    }

    #Oracle part def RejectionOracle :> ConformanceOracle {
        attribute :>> goPackage = "tools/referee/reject";
        attribute :>> reference = "pilot validator";
        attribute :>> baseline = "docs/project/pilot-rejection-baseline.json";
    }

    #Oracle part def DifferentialOracle :> ConformanceOracle {
        attribute :>> goPackage = "tools/referee/diff";
        attribute :>> reference = "pilot validator";
        attribute :>> baseline = "docs/project/pilot-differential-baseline.json";
    }

    #Oracle part def XpectOracle :> ConformanceOracle {
        attribute :>> goPackage = "tools/referee/xpect";
        attribute :>> reference = "pilot Xpect suites";
        attribute :>> baseline = "docs/project/pilot-xpect-baseline.json";
    }

    #Oracle part def ExecutionReferee :> ConformanceOracle {
        attribute :>> goPackage = "tools/referee/exec";
        attribute :>> reference = "pilot expression evaluator";
        attribute :>> baseline = "docs/project/pilot-execution-referee.md";
    }

    // The two behavior referees: OMG's PSSM test suite for state machines and
    // ModelDriven's fUML reference implementation for actions, each translated
    // by rule into the notation and run here, the suite's own outputs the oracle.
    #Oracle part def PssmReferee :> ConformanceOracle {
        attribute :>> goPackage = "tools/referee/pssm";
        attribute :>> reference = "OMG PSSM test suite";
        attribute :>> baseline = "docs/project/pssm-referee-baseline.json";
    }

    #Oracle part def FumlReferee :> ConformanceOracle {
        attribute :>> goPackage = "tools/referee/fuml";
        attribute :>> reference = "fUML reference implementation";
        attribute :>> baseline = "docs/project/fuml-referee-baseline.json";
    }

    // The pilot validator's constraint names, re-extracted from the pinned jar
    // and held against the census document, its probes and the negative corpus.
    #Oracle part def ValidationCensus :> ConformanceOracle {
        attribute :>> goPackage = "tools/census/validation";
        attribute :>> reference = "pilot validator";
        attribute :>> baseline = "docs/project/constraint-manifest.json";
    }

    #Oracle part def GrammarCoverage :> ConformanceOracle {
        attribute :>> goPackage = "tools/census/grammar";
        attribute :>> reference = "OMG Xtext grammars";
        attribute :>> baseline = "docs/project/grammar-coverage-baseline.json";
    }

    // The status figures, counted from the tree into the compliance map's
    // sources; the site build combines those into one page, never committed.
    #Oracle part def DocCounts :> ConformanceOracle {
        attribute :>> goPackage = "tools/census/doccounts";
        attribute :>> reference = "the measured repository";
        attribute :>> baseline = "docs/project/spec-compliance";
        attribute combinedPage : String = "docs/project/spec-compliance.md";
        attribute combinedPageTracked : Boolean = false;
        attribute combiner : String = "scripts/spec_compliance.py";
    }

    // The bundled standard library must parse clean; the gate is in the suite.
    #Oracle part def StdlibConformanceGate :> ConformanceOracle {
        attribute :>> goPackage = "internal/workspace/libs";
        attribute :>> reference = "OMG standard library release";
        attribute :>> baseline = "internal/workspace/libs/stdlib";
        attribute :>> gating = true;
    }

    // The embedded snapshot must be what a fresh build writes; it is generated
    // and gitignored, the suite writes it first, and a build without one skips.
    #Oracle part def StdlibSnapshotGate :> ConformanceOracle {
        attribute :>> goPackage = "internal/workspace/libs";
        attribute :>> reference = "the bundled library files";
        attribute :>> baseline = "internal/workspace/libs/stdlib.snapshot";
        attribute :>> gating = true;
        attribute skipsWithoutSnapshot : Boolean = true;
    }

    // The language-independent contract between the service and its clients:
    // scenarios that are data, run by a reference runner that builds and starts
    // the service itself, and ported by every client in another language.
    #Oracle part def ConformanceSuite :> ConformanceOracle {
        attribute :>> goPackage = "tools/cmd/conformance";
        attribute :>> reference = "the running service";
        attribute :>> baseline = "conformance";
        attribute :>> gating = true;
        attribute protocols : String = "grpc, connect, connect-json, pkg, pkg-connect, mcp";
    }

    // The FMI engine must drive the Modelica Reference-FMUs through the
    // runner; the gate skips until the script has fetched them, and CI
    // requires them.
    #Oracle part def ReferenceFmuGate :> ConformanceOracle {
        attribute :>> goPackage = "tests/fmi";
        attribute :>> reference = "Modelica Reference-FMUs";
        attribute :>> baseline = "scripts/download-reference-fmus.sh";
        attribute :>> gating = true;
        attribute requireEnv : String = "OPENSYSML_REQUIRE_REFERENCE_FMUS";
    }

    // The derived-property differential: every corpus model as the API's
    // element JSON through this writer and the pilot's, bucketed per property.
    #Oracle part def ApiJsonDifferential :> ConformanceOracle {
        attribute :>> goPackage = "tools/referee/apijson";
        attribute :>> reference = "pilot JSON exporter";
        attribute :>> baseline = "docs/project/api-json-differential";
        attribute report : String = "docs/project/api-json-differential.md";
    }
    // What the RDF export survives when loaded into a Flexo MMS stack; opt-in
    // by an environment variable, since the stack must be running.
    #Oracle part def FlexoInterop :> ConformanceOracle {
        attribute :>> goPackage = "tools/referee/flexo";
        attribute :>> reference = "Flexo MMS";
        attribute :>> baseline = "tools/referee/flexo/testdata/interop_expected.txt";
        attribute gateEnv : String = "FLEXO_INTEROP";
    }
    // The censuses over OMG material beyond the validator: the v1-to-v2 mapping,
    // the formal constraints, the notation clause and the grammars' shapes.
    #Oracle part def TransformationCensus :> ConformanceOracle {
        attribute :>> goPackage = "tools/census/transformation";
        attribute :>> reference = "OMG SysML v1 to v2 transformation model";
        attribute :>> baseline = "docs/project/sysml-v1-transformation-census-baseline.json";
        attribute report : String = "docs/project/sysml-v1-transformation-census.md";
    }
    #Oracle part def FormalConstraintCensus :> ConformanceOracle {
        attribute :>> goPackage = "tools/census/formal";
        attribute :>> reference = "KerML and SysML specification constraints";
        attribute :>> baseline = "docs/project/constraint-manifest.json";
    }
    #Oracle part def NotationCensus :> ConformanceOracle {
        attribute :>> goPackage = "tools/census/notation";
        attribute :>> reference = "SysML graphical notation clause";
        attribute :>> baseline = "docs/project/graphical-notation-census-baseline.json";
        attribute report : String = "docs/project/graphical-notation-census.md";
    }
    #Oracle part def MetaclassMap :> ConformanceOracle {
        attribute :>> goPackage = "tools/census/metaclassmap";
        attribute :>> reference = "OMG Xtext grammars";
        attribute :>> baseline = "docs/project/grammar-metaclass-map-baseline.json";
        attribute report : String = "docs/project/grammar-metaclass-map.md";
        attribute command : String = "tools/cmd/grammar-metaclass-map";
    }
    // The specifications' own textual examples, extracted from the pinned
    // PDFs: a per-file ratchet the corpus gate holds and CI requires.
    #Oracle part def SpecExamplesGate :> ConformanceOracle {
        attribute :>> goPackage = "tools/oracle/specexamples";
        attribute :>> reference = "KerML and SysML specification examples";
        attribute :>> baseline = "tests/corpus/testdata/spec_examples_expected.txt";
        attribute :>> gating = true;
        attribute extractor : String = "tools/cmd/spec-examples";
        attribute fetchScript : String = "scripts/download-spec-examples.sh";
        attribute requireEnv : String = "OPENSYSML_REQUIRE_SPEC_EXAMPLES";
    }
    // The API JSON's structure held against the symbol table it was exported
    // from, over every model in the tree.
    #Oracle part def StructureDifferential :> ConformanceOracle {
        attribute :>> goPackage = "internal/translate/export";
        attribute :>> reference = "the symbol table";
        attribute :>> baseline = "internal/translate/export/testdata/structure_differential_expected.txt";
        attribute :>> gating = true;
        attribute testName : String = "TestSymbolStructureMatchesGraphStructure";
    }

    // What the oracles lean on: a pinned reference, an errata overlay for the
    // defects in OMG-published material, and the census the status page reads.
    part def OraclePin :> CodeUnit {
        attribute :>> goPackage = "tools/oracle/baseline";
        attribute recordsPin : Boolean = true;
        attribute recordsBridgeSource : Boolean = true;
        attribute recordsCorpusProvenance : Boolean = true;
    }

    part def Errata :> CodeUnit {
        attribute :>> goPackage = "tools/oracle/errata, internal/workspace/libs/errata";
        attribute overlaysPublishedMaterial : Boolean = true;
    }

    part def StatusCensus :> CodeUnit {
        attribute :>> goPackage = "tools/census/doccounts";
        attribute countsStatusMarkers : Boolean = true;
    }

    part def ConformanceInfrastructure {
        part pins : OraclePin;
        part errata : Errata;
        part census : StatusCensus;
    }

    // --- The whole tool ---------------------------------------------------

    // Every command the Makefile builds, and the ones it releases.
    part def Toolchain {
        attribute releasedCommandCount : Integer = 5;
        attribute wasmCommandCount : Integer = 9;

        part pipeline : AnalysisPipeline;
        part documents : DocumentPipeline;
        part editing : EditorPipeline;
        part forms : RenderingForms;

        part repl : Repl;
        part lsp : LanguageServer;
        part service : ModelService;
        part stdio : StdioService;
        part cli : CommandLine;
        part mcp : McpServer;
        part jupyter : JupyterKernel;
        part syntaxCommand : SyntaxCommand;
        part engineCommand : EngineCommand;
        part coreCommand : CoreCommand;
        part wasm : CombinedCommand;

        part goClient : GoClient;
        part python : PythonClient;
        part node : NodeClient;
        part rust : RustClient;
        part java : JavaClient;
        part julia : JuliaClient;
        part matlab : MatlabClient;
        part vscode : VsCodeExtension;
        part emacs : EmacsMode;
        part treeSitter : TreeSitterGrammars;
        part mdk : MagicMDK;
        part syson : SysonMDK;
        part kernelPackage : JupyterKernelPackage;
        part jupyterlab : JupyterLabExtension;
        part mcpPackage : McpNpmPackage;
        part projects : ProjectDiscovery;

        part exporter : Exporter;
        part migrator : Migrator;
        part codegen : CodeGenerator;
        part oslc : OslcQuery;

        part rejection : RejectionOracle;
        part differential : DifferentialOracle;
        part xpect : XpectOracle;
        part execution : ExecutionReferee;
        part pssm : PssmReferee;
        part fuml : FumlReferee;
        part validation : ValidationCensus;
        part grammar : GrammarCoverage;
        part counts : DocCounts;
        part stdlib : StdlibConformanceGate;
        part snapshotGate : StdlibSnapshotGate;
        part suite : ConformanceSuite;
        part fmuGate : ReferenceFmuGate;
        part apiJson : ApiJsonDifferential;
        part flexo : FlexoInterop;
        part transformation : TransformationCensus;
        part formal : FormalConstraintCensus;
        part notation : NotationCensus;
        part metaclassMap : MetaclassMap;
        part specExamples : SpecExamplesGate;
        part structure : StructureDifferential;
        part conformance : ConformanceInfrastructure;

        connection replDrives : ArtifactChannel connect repl.pipeline to pipeline.textIn;
        connection lspDrives : ArtifactChannel connect lsp.pipeline to pipeline.textIn;
        connection serviceDrives : ArtifactChannel connect service.pipeline to pipeline.textIn;
        connection cliDrives : ArtifactChannel connect cli.pipeline to pipeline.textIn;
        connection mcpDrives : ArtifactChannel connect mcp.pipeline to pipeline.textIn;
        connection jupyterWrapsRepl : ArtifactChannel connect jupyter.repl to repl.pipeline;
        connection syntaxDrives : ArtifactChannel connect syntaxCommand.pipeline to pipeline.textIn;
        connection engineDrives : ArtifactChannel connect engineCommand.pipeline to pipeline.textIn;
        connection coreDrives : ArtifactChannel connect coreCommand.pipeline to pipeline.textIn;
        connection wasmDrives : ArtifactChannel connect wasm.pipeline to pipeline.textIn;

        connection replAsks : RequestChannel connect repl.questions to pipeline.questionsIn;
        connection serviceAsks : RequestChannel connect service.questions to pipeline.questionsIn;
        connection cliAsks : RequestChannel connect cli.questions to pipeline.questionsIn;

        connection goCalls : ArtifactChannel connect goClient.service to service.pipeline;
        connection pythonCalls : ArtifactChannel connect python.service to service.pipeline;
        connection nodeCalls : ArtifactChannel connect node.service to service.pipeline;
        connection rustCalls : ArtifactChannel connect rust.service to service.pipeline;
        connection javaCalls : ArtifactChannel connect java.service to service.pipeline;
        connection juliaCalls : ArtifactChannel connect julia.service to service.pipeline;
        connection matlabCalls : ArtifactChannel connect matlab.service to service.pipeline;
        connection editorSpeaksLsp : ArtifactChannel connect vscode.languageClient to lsp.pipeline;
        connection emacsSpeaksLsp : ArtifactChannel connect emacs.languageClient to lsp.pipeline;
        connection packageShipsMcp : ArtifactChannel connect mcpPackage.server to mcp.pipeline;
        connection mdkUsesJava : ArtifactChannel connect mdk.serviceClient to java.service;
        connection sysonUsesJava : ArtifactChannel connect syson.serviceClient to java.service;
        connection packageShipsKernel : ArtifactChannel connect kernelPackage.kernel to jupyter.pipeline;
        connection labExtensionShipsIn : ArtifactChannel connect jupyterlab.notebook to kernelPackage.kernel;

        connection documentsRead : ArtifactChannel connect pipeline.textIn to documents.modelIn;
        connection findingsToEditors : DiagnosticChannel connect pipeline.diagnosticsOut to editing.findingsIn;
        connection editsBack : ArtifactChannel connect editing.textOut to pipeline.textIn;
    }

    part opensysml : Toolchain;

    requirement documentsAreTraceable : DocumentsCarryTheirProvenance {
        subject documents = opensysml.documents;
    }

    requirement def ViewsSayWhatTheyCannotRender {
        doc /* Every rendering kind is recognized, and the ones not produced
             * say so instead of being drawn as something else. */
        subject views : ViewEngine;
        require constraint {
            views.recognizedKinds == 14 and views.supportedKinds == 12
                and not views.textual.supported and not views.geometry.supported
                and views.sequence.supported and views.matrix.supported
        }
    }

    requirement viewsAreHonest : ViewsSayWhatTheyCannotRender {
        subject views = opensysml.documents.views;
    }
}