### Install Go client

Source: https://opensysml.org/guide/09-clients

Installs the Go client module. The engine and SysML standard library are included in the module, so no additional setup is needed.

```bash
go get github.com/Open-MBEE/OpenSysML@latest

```

--------------------------------

### Install OpenSysML binaries with make install or manual move

Source: https://opensysml.org/guide/01-install

Installs the built binaries to $GOPATH/bin using make install, or manually moves them to /usr/local/bin with sudo. The manual move requires superuser privileges.

```bash
make install     # installs to $GOPATH/bin
# OR
sudo mv bin/sysml bin/sysml-lsp bin/sysml-grpc /usr/local/bin/
```

--------------------------------

### Install @opensysml/client with npm

Source: https://opensysml.org/reference/node-api

Install the package once the first release is published. Nothing is published yet, so a checkout builds it with 'npm install && npm run build' in clients/node.

```bash
npm install @opensysml/client        # once the first release is published

```

--------------------------------

### Usage Example

Source: https://opensysml.org/reference/api

Example of using the runtime API to instantiate a model, get feature values, and invoke calculations.

```APIDOC
## Usage

### Description
Tier 1-3 (Instances & Expressions) usage example.

### Example
```
// The model-derived part (memoized shapes, targets, literals) is built once and
// shared by every context over it; a context is one run's own state.
shared := runtime.NewModel(model, resolver)
// Honour the OPENSYSML_MAX_* budgets instead of the defaults with:
//   budgets, err := runtime.BudgetsFromEnv()
//   err = ctx.SetBudgets(budgets)
ctx := runtime.NewContext(shared, runtime.DefaultMaxSteps)
inst, _ := ctx.Instantiate(wheelSym)
fv, _ := inst.GetFeatureValue(ctx, "diameter")
result, _ := ctx.InvokeCalc(addSym, []Value{v1, v2}, scope)
```
```

--------------------------------

### Install with Go toolchain

Source: https://opensysml.org/guide/01-install

Use the Go toolchain to install OpenSysML and its LSP server locally, which avoids the quarantine attribute since binaries are built locally.

```bash
go install github.com/Open-MBEE/OpenSysML/cmd/sysml@latest
go install github.com/Open-MBEE/OpenSysML/cmd/sysml-lsp@latest
```

--------------------------------

### Command-line examples for requirements model

Source: https://opensysml.org/manual/authoring

Shows three sysml commands to run a query and render the document in Markdown and HTML forms using the requirements.sysml example file.

```shell
$ sysml docs/manual/examples/requirements.sysml -run-query "Requirements::Reqs root=Requirements::spec"
$ sysml docs/manual/examples/requirements.sysml -render-document Requirements::RequirementsReport
$ sysml docs/manual/examples/requirements.sysml -render-document Requirements::RequirementsReport -doc-form html

```

--------------------------------

### Install Python client

Source: https://opensysml.org/guide/09-clients

Installs the Python client via pip and sets the OPENSYSML_GRPC_VERSION environment variable to request a sysml-grpc release. Alternatively, install sysml-grpc yourself.

```bash
pip install opensysml
export OPENSYSML_GRPC_VERSION=latest   # or install sysml-grpc yourself

```

--------------------------------

### Workspace Usage Example

Source: https://opensysml.org/reference/api

Shows how to create a workspace, add a document, and retrieve diagnostics for it.

```go
ws := model.NewWorkspace()
doc := ws.AddDocument("example.sysml", src)
diagnostics := ws.Diagnostics("example.sysml")
```

--------------------------------

### Install OpenSysML binaries and manual pages with make install-tree

Source: https://opensysml.org/guide/01-install

Installs binaries and manual pages to a custom prefix using make install-tree, then verifies with man sysml. This method respects GNU variables like DESTDIR and prefix for packaging.

```bash
sudo make install-tree prefix=/usr/local
man sysml
```

--------------------------------

### Start Interactive REPL (Default)

Source: https://opensysml.org/reference/cli

Starts the SysML REPL with no arguments, entering interactive mode. Use when you want to explore or evaluate expressions interactively.

```bash
sysml

```

--------------------------------

### Install opensysml from PyPI or from a checkout

Source: https://opensysml.org/guide/09-clients

Install the opensysml package from PyPI or from a local checkout. The dependencies grpcio, protobuf>=7.35.1, filelock, and psutil are installed automatically. Requires CPython 3.10 or later.

```bash
pip install opensysml             # from PyPI
pip install -e clients/python/          # or from a checkout, at the repository root
```

--------------------------------

### opensysml/views response example

Source: https://opensysml.org/reference/lsp

Example response from the opensysml/views request, listing views and pseudo-views. Unsupported views include a reason.

```json
{
  "views": [
    { "name": "KitViews::widgetParts", "kind": "interconnection", "supported": true },
    { "name": "KitViews::widgetSequence", "kind": "sequence", "supported": true },
    {
      "name": "KitViews::widgetGeometry",
      "kind": "geometry",
      "supported": false,
      "reason": "KitViews::widgetGeometry: geometry rendering (view def GeometryView) is not supported"
    }
  ],
  "pseudoViews": ["#action", "#interconnection", "#sequence", "#state", "#table", "#tree"]
}
```

--------------------------------

### Launch the SysML v2 REPL

Source: https://opensysml.org/guide/02-first-model

Starts the interactive SysML v2 REPL. The prompt shows the version and available commands.

```text
$ sysml
SysML v2 REPL — %help for commands, Ctrl-D to exit
sysml> 
```

--------------------------------

### Start REPL and evaluate a declaration

Source: https://opensysml.org/guide/04-repl

Shows a complete REPL session: starting sysml, importing ScalarValues, defining a package with a part definition, and evaluating a feature. The import is required to resolve Real; without it, the declaration is rejected with 'unresolved reference: Real'.

```text
$ sysml
SysML v2 REPL — %help for commands, Ctrl-D to exit
sysml> private import ScalarValues::*;
✓ import ScalarValues::*
sysml> package Demo { part def Wheel { attribute diameter : Real = 16.0; } }
✓ package Demo
sysml> %eval Demo::Wheel::diameter
✓ Demo::Wheel::diameter
  = 16.0

```

--------------------------------

### Install via Homebrew (macOS)

Source: https://opensysml.org/guide/01-install

Installs OpenSysML using Homebrew with the fully qualified tap name, avoiding the Gatekeeper prompt. This is the recommended path for macOS.

```bash
brew install Open-MBEE/tap/opensysml

```

--------------------------------

### Stage OpenSysML installation for packaging with DESTDIR

Source: https://opensysml.org/guide/01-install

Stages the installation into a package build root without writing outside it. The DESTDIR variable is set to the package directory and prefix to /usr, allowing distribution packages to collect files.

```bash
make install-tree DESTDIR="$pkgdir" prefix=/usr
```

--------------------------------

### Install via Homebrew with explicit tap trust (macOS)

Source: https://opensysml.org/guide/01-install

Alternative Homebrew installation that taps the repository, trusts the formula (or tap), and then installs. Required when not using the fully qualified name due to Homebrew 6 trust requirements.

```bash
brew tap Open-MBEE/tap
brew trust --formula Open-MBEE/tap/opensysml   # or: brew trust Open-MBEE/tap, for the whole tap
brew install opensysml

```

--------------------------------

### Install OpenSysML with Homebrew or Go

Source: https://opensysml.org/

Install OpenSysML on macOS using Homebrew or with a Go toolchain. The Homebrew command installs the 'opensysml' tap, while the Go command installs the 'sysml' command-line tool.

```bash
# macOS
brew install Open-MBEE/tap/opensysml

# with a Go toolchain
go install github.com/Open-MBEE/OpenSysML/cmd/sysml@latest
```

--------------------------------

### Engine manifest entry example

Source: https://opensysml.org/reference/external-engines

Example of an engine manifest entry in JSON, showing the required members and their values for a spin-bridge engine.

```json
{
  "kind": "engine",
  "name": "spin-bridge",
  "version": "1.4.0",
  "command": ["/opt/spin-bridge/bin/spin-bridge", "--serve"],
  "transport": "stdio",
  "protocol": 1,
  "answers": ["holds", "outcomes"],
  "subjects": ["action"],
  "model": ["sources", "graphs:1"],
  "bounds": ["depth", "steps", "runs"],
  "witness": "schedule",
  "authority": "bounded"
}
```

--------------------------------

### Download and install Linux release archive

Source: https://opensysml.org/guide/01-install

Downloads the Linux amd64 tarball, extracts it, moves the binaries to /usr/local/bin, and makes them executable. Use opensysml-linux-arm64.tar.gz on arm64.

```bash
wget https://github.com/Open-MBEE/OpenSysML/releases/latest/download/opensysml-linux-amd64.tar.gz
tar xzf opensysml-linux-amd64.tar.gz
sudo mv sysml sysml-lsp /usr/local/bin/
chmod +x /usr/local/bin/sysml /usr/local/bin/sysml-lsp

```

--------------------------------

### Install Node/TypeScript client

Source: https://opensysml.org/guide/09-clients

Installs the Node client package and sets OPENSYSML_GRPC_VERSION to request a sysml-grpc release. The package is not published yet, so this command is for after the first release.

```bash
npm install @opensysml/client          # once the first release is published
export OPENSYSML_GRPC_VERSION=latest

```

--------------------------------

### opensysml/views request example

Source: https://opensysml.org/reference/lsp

Example request body for the opensysml/views request, specifying the text document URI.

```json
{ "textDocument": { "uri": "file:///tmp/kit.sysml" } }
```

--------------------------------

### Install Rust client from git

Source: https://opensysml.org/guide/09-clients

Adds the Rust client as a git dependency. Not published yet, so use a git or path dependency. Requires Rust 1.83 or later.

```toml
[dependencies]
opensysml = { git = "https://github.com/Open-MBEE/OpenSysML.git", branch = "main" }

```

--------------------------------

### Start action executor for Timed::pinger

Source: https://opensysml.org/guide/06-behavior

Starts the action executor for the pinger action. The output shows the executor is running with one token and suggests using %step, %tokens, or %continue.

```sysml
sysml> %action Timed::pinger
✓ Started action executor for "Timed::pinger"
  State: Running
  Tokens: 1

Use %step to advance, %tokens to inspect, %continue to run to completion
```

--------------------------------

### RunSweep request and response example

Source: https://opensysml.org/reference/wire-contract

Example of a RunSweep request and its response, showing a sweep over parameter 'b' with integer values -1, 0, and 1. The response includes rows with inputs, outputs, and for the failed row, an error and failure reason. The example demonstrates the response format with parameters and rows.

```shell
$ … /RunSweep -d '{"modelHash":"a6dc…4849","symbolId":"An::CostAnalysis","subjectSymbolId":"An::barge","ranges":[{"parameter":"tax","start":{"realValue":0.0},"end":{"realValue":1.0},"step":{"realValue":0.5}}]}'
```

```json
{"rows":[{"inputs":[{"name":"b","value":{"intValue":"-1"}}],"outputs":[{"name":"result","value":{"realValue":-4}}],"elapsedMicros":"18"},
         {"inputs":[{"name":"b","value":{"intValue":"0"}}],"elapsedMicros":"6",
          "error":"calc An::Ratio: evaluating the returned expression: division by zero","failureReason":"FAILURE_REASON_EVALUATION"},
         {"inputs":[{"name":"b","value":{"intValue":"1"}}],"outputs":[{"name":"result","value":{"realValue":4}}]}],
 "parameters":["b"]}
```

--------------------------------

### Five ways to provide the sysml-grpc binary

Source: https://opensysml.org/guide/09-clients

Commands and environment variables to provide the sysml-grpc binary. Options include downloading a release, setting OPENSYSML_GRPC_VERSION, building from source, setting OPENSYSML_BINARY, or installing on PATH. The binary is located in the order: $OPENSYSML_BINARY, ~/.opensysml/bin/sysml-grpc, a release download, then sysml-grpc on $PATH.

```bash
# 1. Download the release build (verified against the digest pinned in opensysml)
python -c "from opensysml.binary import download_binary; download_binary('latest')"

# 2. Have opensysml.connect() download it on first use
export OPENSYSML_GRPC_VERSION=latest      # or a tag like v0.0.5

# 3. Build from source
make build-grpc && mkdir -p ~/.opensysml/bin && cp bin/sysml-grpc ~/.opensysml/bin/

# 4. Name a build to start, wherever it is
export OPENSYSML_BINARY=$PWD/bin/sysml-grpc

# 5. Install one on $PATH, with a package manager or `go install`
```

--------------------------------

### Install Java client with Maven

Source: https://opensysml.org/guide/09-clients

Adds the Java client dependency to a Maven project. The version is a snapshot and not published yet; build from source with 'make build && mvn -f clients/java/pom.xml install'.

```xml
<dependency>
  <groupId>org.openmbee</groupId>
  <artifactId>opensysml-client</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>

```

--------------------------------

### Create connections: default, private, and external

Source: https://opensysml.org/reference/rust-api

Shows three ways to create a Connection: connect() uses the $OPENSYSML_SERVICE environment variable or a private child, private() starts a child process, and external() connects to a service on a given host and port.

```rust
use opensysml::Connection;

let connection = Connection::connect()?;                 // $OPENSYSML_SERVICE, else private
let private = Connection::private()?;                    // a child of this process
let external = Connection::external("localhost", 50051)?; // a service someone else runs

```

--------------------------------

### Download and install macOS release archive (fallback)

Source: https://opensysml.org/guide/01-install

Downloads the macOS arm64 tarball with curl, extracts it, and moves the binaries to /usr/local/bin. Use opensysml-darwin-amd64.tar.gz on Intel.

```bash
# Apple Silicon; use opensysml-darwin-amd64.tar.gz on Intel
curl -fL -o opensysml.tar.gz https://github.com/Open-MBEE/OpenSysML/releases/latest/download/opensysml-darwin-arm64.tar.gz
tar xzf opensysml.tar.gz
sudo mv sysml sysml-lsp /usr/local/bin/

```

--------------------------------

### Define a package with an action and part that performs it

Source: https://opensysml.org/guide/06-behavior

Defines a SysML v2 package Q with an action Main that accepts a Go message and updates a total, and a part pd that performs the action. This is the setup for the subsequent command-line interactions.

```sysml
sysml> package Q {
  ...>     private import ScalarValues::*;
  ...>     attribute def Go { attribute n : Integer; }
  ...>     action def Main {
  ...>         out total : Integer = 0;
  ...>         first start;
  ...>         then action w1 accept g : Go;
  ...>         then action a1 assign total := total + g.n;
  ...>         then done;
  ...>     }
  ...>     part def PD { perform action main : Main; }
  ...>     part pd : PD;
  ...> }
```

--------------------------------

### Run the analysis case with sysml command

Source: https://opensysml.org/guide/06-behavior

Runs the analysis case defined in the previous example using the sysml command with the -analysis flag. The output shows the package and case are verified, and the computed total and result values are displayed.

```shell
$ sysml -analysis test::steps steps.sysml
✓ package test
✓ test::steps
  total = 66.0
  result = 60.0

```

--------------------------------

### ExecuteAction with default schedule (reverse)

Source: https://opensysml.org/reference/wire-contract

Example request and response for ExecuteAction with no schedule specified, showing the default reverse policy and a choice-point diagnostic.

```shell
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::tally"}'
{"outputs":{"leftCount":{"intValue":"1"},"rightCount":{"intValue":"10"}},"diagnostics":[{"severity":"info","message":"choice point: step 3: tokens 2@left, 3@right (unordered; took 3@right first)","span":{"file":"tally.sysml","startLine":2,"startCol":2,"endLine":20,"endCol":2},"code":"choice-point"}]}
```

--------------------------------

### Witness output with input lines

Source: https://opensysml.org/reference/cli

Example of a witness output showing an input line and the absence of choice points, as produced by the `smt` engine.

```text
input limit = -1
no choice points

…

```

--------------------------------

### Standard library URI scheme example

Source: https://opensysml.org/guide/08-editors

Shows the URI format for a standard library document under the sysml-stdlib scheme, used to locate files within the bundled library.

```text
sysml-stdlib:///Kernel%20Libraries/Kernel%20Data%20Type%20Library/ScalarValues.kerml
```

--------------------------------

### In-body failure examples for various methods

Source: https://opensysml.org/reference/wire-contract

Examples of in-body failure responses for Instantiate, ExecuteState, and Evaluate methods. Each shows the error message and optional failureReason. The Python client maps 'symbol not found:' to SymbolNotFoundError and other errors to ModelError or ExecutionError.

```text
$ … /EvaluateCalc -d '{"modelHash":"b4e0…ded9","symbolId":"Demo::sedan"}'
{"error":"calc invocation failed: not a calc: Demo::sedan is a part usage, not a calc definition or usage","failureReason":"FAILURE_REASON_WRONG_KIND"}
```

```text
{"error":"symbol not found: Demo::Nope"}                                    Instantiate
{"error":"state machine not found: Test::NoMachine"}                        ExecuteState
{"error":"action execution failed: initialize action: invalid action flow: no initial node found in action noStart"}
{"error":"evaluation failed: object has no such feature: member nothing not found in instance"}  Evaluate
{"error":"evaluation failed: unresolved reference: sqrt — did you mean RealFunctions::sqrt or QuantityCalculations::sqrt?"}
```

--------------------------------

### Diagnostic JSON shape example

Source: https://opensysml.org/reference/wire-contract

Example of a diagnostic finding in JSON, showing severity, message, span, and code fields. The span includes file, start/end lines and columns, with 1-based lines/columns and exclusive end positions.

```json
{"severity":"error","message":"expected a namespace member","span":{"file":"syntax_error.sysml","startLine":1,"startCol":16,"endLine":1,"endCol":23},"code":"syntax"}
```

--------------------------------

### Validate and strict-validate the defer example

Source: https://opensysml.org/guide/03-command-line

Run `sysml -validate` and `sysml -strict -validate` on the same file. The first produces a warning and exits 0; the second promotes the warning to an error and exits 2. This demonstrates how `-strict` turns the run into a portability check.

```bash
$ sysml -validate monitor.sysml; echo "exit=$?"
monitor.sysml:6:13: warning: `defer <event>;` is an OpenSysML extension with no SysML v2 production: no notation states a deferred event
            defer Alarm;
            ^~~~~
✓ package M
✓ monitor.sysml: no errors
exit=0

$ sysml -strict -validate monitor.sysml; echo "exit=$?"
monitor.sysml:6:13: error: `defer <event>;` is an OpenSysML extension with no SysML v2 production: no notation states a deferred event
            defer Alarm;
            ^~~~~
sysml: monitor.sysml did not analyse cleanly; no check was made
exit=2

```

--------------------------------

### Runtime usage: instantiate model and invoke calculation

Source: https://opensysml.org/reference/api

Shows how to create a runtime context from a shared model, instantiate a symbol, get a feature value, and invoke a calculation. The shared model is built once and reused across contexts; budgets can be set from environment variables with OPENSYSML_MAX_*.

```go
// The model-derived part (memoized shapes, targets, literals) is built once and
// shared by every context over it; a context is one run's own state.
shared := runtime.NewModel(model, resolver)
// Honour the OPENSYSML_MAX_* budgets instead of the defaults with:
//   budgets, err := runtime.BudgetsFromEnv()
//   err = ctx.SetBudgets(budgets)
ctx := runtime.NewContext(shared, runtime.DefaultMaxSteps)
inst, _ := ctx.Instantiate(wheelSym)
fv, _ := inst.GetFeatureValue(ctx, "diameter")
result, _ := ctx.InvokeCalc(addSym, []Value{v1, v2}, scope)
```

--------------------------------

### JSON check output with plan and results

Source: https://opensysml.org/reference/cli

Example JSON response for a failing check, showing the plan with engine selection and steps, and results with bounds, witness, and standing. The output includes the reason for the violation and the witness schedule.

```json
{"checks": [{"subject": "Rover::Overweight", "status": "fails",
  "lines": ["✗ Constraint Rover::Overweight failed",
            "  Assertion evaluated to false: 250.0 <= 200.0",
            "  standing: violated (witnessed: 1 run under reverse)"],
  "plan": {"engine": "auto", "standing": "violated (witnessed: 1 run under reverse)",
           "steps": [{"engine": "run", "status": "answered"}]},
  "results": [{"engine": "run", "claim": "violated", "strength": "witnessed",
               "bounds": [{"name": "steps", "limit": 10000000, "reached": false},
                          {"name": "elements", "limit": 1000000, "reached": false}],
               "witness": {"schedule": "reverse", "choices": []},
               "reason": "constraint Overweight: assertion evaluated to false: 250.0 <= 200.0",
               "standing": "violated (witnessed: 1 run under reverse)"}]
}]}
```

--------------------------------

### action_explore_three_writers.trace.order with partial order constraints

Source: https://opensysml.org/guide/06-behavior

Example of a `.trace.order` file that specifies the partial order the library fixes, as `earlier < later` constraints over trace labels. Blank lines and `#` comments are skipped. The harness checks the trace against these constraints beside the exact golden, so a fixture states what must hold without pinning what may vary.

```text
# The fork precedes every branch; the join waits for all three.
split < a
split < b
split < c
a < sync
b < sync
c < sync

```

--------------------------------

### Build and run the LSP server

Source: https://opensysml.org/internals/architecture

Builds the sysml-lsp binary and runs it in stdio mode for editor integration. Requires Go toolchain.

```shell
go build -o sysml-lsp ./cmd/sysml-lsp
./sysml-lsp  # stdio mode for editors

```

--------------------------------

### Load model and evaluate from Node.js

Source: https://opensysml.org/guide/09-clients

Imports `loads` from `@opensysml/client` to load a SysML model from a string, then evaluates an expression, gets a symbol, and instantiates a part. Uses `await using` for async-disposable cleanup. The package is not published yet; build it from a checkout with `npm install && npm run build` in `clients/node`.

```javascript
import { loads } from "@opensysml/client";

await using model = await loads(`package Demo {
  part def Wheel { attribute radius : ScalarValues::Real = 0.3; }
  part def Car { part wheels : Wheel[4]; attribute mass : ScalarValues::Real = 1500.0; }
}`);

const value = await model.eval("2 + 2");
const car = await model.symbol("Demo::Car");
const tree = await model.instantiate("Demo::Car");
tree.get("wheels");
```

--------------------------------

### RunAnalysis with verification verdicts

Source: https://opensysml.org/reference/wire-contract

Runs a verification case and returns outputs, verdicts, instances, and verification verdicts. The example shows a pass verdict for the case and a pass for the subcase.

```shell
$ … /RunAnalysis -d '{"modelHash":"96c9…994d","symbolId":"Ver::checkSlow"}'
{"outputs":[{"name":"result","value":{"enumLiteral":{"literalId":"VerificationCases::VerdictKind::pass","enumerationId":"VerificationCases::VerdictKind","name":"VerdictKind::pass"}}}],"verdicts":[{"kind":"objective","elementId":"Ver::checkSlow::obj","element":"obj","holds":true,"instanceId":"1","instanceTypeId":"Ver::slow"}],"instances":[…],"verificationVerdicts":[{"caseId":"Ver::checkSlow","kind":"pass"}]}
```

--------------------------------

### REPL refusal of explore schedule

Source: https://opensysml.org/guide/06-behavior

Shows the REPL error when `%schedule explore` is used, explaining that `%action` and `%state` step one run and cannot replay from the start. Use this to understand why the REPL rejects `explore` and how to run it instead.

```text
sysml> %schedule explore
error: explore replays a behavior from the start once per linearization, which %action and %state, stepping one run, cannot do: run `sysml -schedule explore -action <name>` (or -state, -analysis, -calc), or a request with schedule "explore"
```

--------------------------------

### Command-line migration examples

Source: https://opensysml.org/reference/sysml-v1-migration

Shows four command-line invocations of the `sysml` tool to convert SysML v1 models to SysML v2 notation or RDF, with optional migration reports and explicit input format. The input format is inferred from `.xmi`, `.uml`, and `.mdzip` extensions; other names require `-from xmi`. `-convert xmi` is refused because v2 has no v1 form.

```bash
sysml Model.xmi   -convert sysml -o Model.sysml -migration-report Model.report.txt
sysml Model.uml   -convert ttl   -o Model.ttl   -migration-report Model.report.json
sysml Model.mdzip -convert sysml -o Model.sysml
sysml export.xml  -convert sysml -from xmi
```

--------------------------------

### Run conformance suite for all protocols

Source: https://opensysml.org/reference/service-transports

Runs the entire conformance scenario list against all three protocols (gRPC, Connect with protobuf body, Connect with JSON body) using make conformance.

```shell
$ make conformance                                    # all three protocols

```

--------------------------------

### ExecuteAction with declared schedule and invalid seed error

Source: https://opensysml.org/reference/wire-contract

Two examples: one showing the response with the 'declared' schedule, and one showing a 400 error for an invalid seed value.

```shell
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::tally","schedule":"declared"}'
{"outputs":{"leftCount":{"intValue":"1"},"rightCount":{"intValue":"10"}},"diagnostics":[{"severity":"info","message":"choice point: step 3: tokens 2@left, 3@right (unordered; took 2@left first)","span":{"file":"tally.sysml","startLine":2,"startCol":2,"endLine":20,"endCol":2},"code":"choice-point"}]}
```

```shell
$ … /ExecuteAction -d '{"modelHash":"81b1…73fc","actionSymbolId":"Test::tally","schedule":"seed:abc"}'
HTTP/1.1 400 Bad Request
{"code":"invalid_argument","message":"invalid scheduling policy \"seed:abc\": seed \"abc\" is not a non-negative decimal integer"}
```

--------------------------------

### Timed package with action pinger and state listener

Source: https://opensysml.org/guide/06-behavior

Defines a package with an action that waits 5 seconds, increments a counter, and sends a Ping signal to a listener state machine. The listener accepts Ping and transitions to pinged. This example is used to demonstrate the shared clock and %advance behavior.

```sysml
sysml> package Timed {
  ...>     item def Ping;
  ...>     action pinger {
  ...>         attribute count = 0;
  ...>         first start;
  ...>         then action wait accept after 5 [SI::s];
  ...>         then action tick assign count := count + 1;
  ...>         then send new Ping() to listener;
  ...>         then done;
  ...>     }
  ...>     state listener {
  ...>         entry; then idle;
  ...>         state idle;
  ...>         transition idle_pinged first idle accept Ping then pinged;
  ...>         state pinged;
  ...>     }
  ...> }
✓ package Timed
```

--------------------------------

### Run all tests and build

Source: https://opensysml.org/internals/architecture

Use `go test ./...` to run all tests and `go build ./...` to ensure a clean build. These commands verify that all tests pass and the project compiles without errors.

```bash
go test ./...
```

```bash
go build ./...
```

--------------------------------

### RunAnalysis with symbolId An::shipCost

Source: https://opensysml.org/reference/wire-contract

Runs an analysis case by symbolId, returning outputs and verdicts. The example shows a successful run with a real value output and an objective verdict that holds.

```shell
$ … /RunAnalysis -d '{"modelHash":"e43c…9a2a","symbolId":"An::shipCost"}'
{"outputs":[{"name":"total","value":{"realValue":12}}],"verdicts":[{"kind":"objective","elementId":"An::CostAnalysis::affordable","element":"affordable","holds":true}]}
```

--------------------------------

### VerifyConstraint response with instances

Source: https://opensysml.org/reference/wire-contract

The response for the third VerifyConstraint example, showing a verdict without a holds key (indicating false) and the instances array with the instantiated sedan. The instanceId and instanceTypeId fields are present because a subject was instantiated.

```json
{
  "verdict": {
    "kind": "constraint",
    "elementId": "Demo::Vehicle::massLight",
    "element": "Demo::Vehicle::massLight",
    "condition": "mass < 100.0",
    "instanceId": "1",
    "instanceTypeId": "Demo::sedan"
  },
  "instances": [
    {
      "id": "1",
      "typeSymbolId": "Demo::sedan",
      "featureValues": {
        "lightEnough":  {"featureName": "lightEnough"},
        "mass":         {"featureName": "mass", "value": {"realValue": 1200}, "materialized": true},
        "massLight":    {"featureName": "massLight"},
        "massPositive": {"featureName": "massPositive"},
        "tiny":         {"featureName": "tiny"}
      }
    }
  ]
}
```

--------------------------------

### Load a SysML file with sysml

Source: https://opensysml.org/reference/cli

Loads the file 'demo.sysml' and summarizes the declared package and part definition. The REPL prompt is shown after the summary.

```shell
$ sysml demo.sysml
package Demo
  part def Vehicle {
    attribute speed : Real;
  }
SysML v2 REPL — %help for commands, Ctrl-D to exit
sysml> 

```

--------------------------------

### Execute actions and state machines

Source: https://opensysml.org/guide/09-clients

Shows how to run actions and state machines on the model using execute_action and execute_state, including passing inputs and receiving outputs. Also demonstrates the explore_action method for exploring all outcomes.

```python
model.execute_action("Demo::addFive", inputs={"result": 10})   # {'result': 15}
model.execute_state("Demo::Machine", events=["go"])            # {'states_visited': [...], ...}
```

```python
exploration = model.explore_action("Demo::race")          # schedule="explore" by default
for outcome in exploration:                               # canonical order, the same every time
    print(outcome.outputs, outcome.linearizations, outcome.witness)
exploration.complete, exploration.runs, exploration.budgets_hit   # (True, 6, [])
model.explore_action("Demo::race", schedule="explore:runs=2").budgets_hit   # ['runs']
```

--------------------------------

### RunAnalysis command and response with evaluations

Source: https://opensysml.org/reference/wire-contract

Shows a `RunAnalysis` command with a JSON request and the corresponding response containing `evaluations` for three alternatives. The response includes `outputs`, `verdicts`, `instances`, and `evaluations` with `selected` and `tied` flags. The example illustrates a tie where two alternatives have the same result, with the first selected and the second marked as tied.

```json
$ … /RunAnalysis -d '{"modelHash":"3f1a…50c2","symbolId":"Trade::lightest","schedule":"explore"}'
{"outputs":[{"name":"selectedAlternative","value":{"instanceId":"2"}}],
 "verdicts":[{"kind":"objective","elementId":"Trade::lightest::tradeStudyObjective","element":"tradeStudyObjective","holds":true}],
 "instances":[{"id":"1","typeSymbolId":"Trade::a",…},{"id":"2","typeSymbolId":"Trade::b",…},{"id":"3","typeSymbolId":"Trade::c",…}],
 "evaluations":[{"functionId":"Trade::lightest::evaluationFunction","arguments":[{"instanceId":"1"}],"result":{"realValue":30}},
                {"functionId":"Trade::lightest::evaluationFunction","arguments":[{"instanceId":"2"}],"result":{"realValue":10},"selected":true},
                {"functionId":"Trade::lightest::evaluationFunction","arguments":[{"instanceId":"3"}],"result":{"realValue":10},"tied":true}]}
```

--------------------------------

### Parse, evaluate, and re-parse with -cache-size 1

Source: https://opensysml.org/reference/wire-contract

Shows a sequence of commands against a service started with -cache-size 1. The first ParseSources returns a hash, Evaluate succeeds, then parsing a second model evicts the first. Evaluating the evicted hash returns 404 with "model not found:", and re-parsing the original document returns the same deterministic hash.

```shell
$ … /ParseSources -d '{"documents":[{"name":"a.sysml","content":"package A { attribute x = 1; }"}]}'
{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","roots":[{"kind":"RootNamespace","childIds":["A"]}]}

$ … /Evaluate -d '{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","expression":"A::x"}'
{"result":{"intValue":"1"}}

$ … /ParseSources -d '{"documents":[{"name":"b.sysml","content":"package B { attribute y = 2; }"}]}'
{"modelHash":"ca693643bf449df4d2904900963596195409a34bbc51f243964952077ab99eb3","roots":[{"kind":"RootNamespace","childIds":["B"]}]}

$ … /Evaluate -d '{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","expression":"A::x"}'
HTTP/1.1 404 Not Found
{"code":"not_found","message":"model not found: f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae"}

$ … /ParseSources -d '{"documents":[{"name":"a.sysml","content":"package A { attribute x = 1; }"}]}'
{"modelHash":"f90104e75e9172ab29c8648e3529a103e178756d35b4643d03c8c64419eaabae","roots":[{"kind":"RootNamespace","childIds":["A"]}]}

```

--------------------------------

### RunAnalysis with subjectSymbolId An::barge

Source: https://opensysml.org/reference/wire-contract

Runs an analysis case with a subject symbol ID and named arguments, returning outputs, verdicts, and instances. The example shows a real value of 37 and an objective verdict that holds for the barge instance.

```shell
$ … /RunAnalysis -d '{"modelHash":"e43c…9a2a","symbolId":"An::CostAnalysis","subjectSymbolId":"An::barge","namedArguments":{"limit":{"realValue":50.0}}}'
{"outputs":[{"name":"total","value":{"realValue":37}}],"verdicts":[{"kind":"objective","elementId":"An::CostAnalysis::affordable","element":"affordable","holds":true,"instanceId":"1","instanceTypeId":"An::barge"}],"instances":[{"id":"1","typeSymbolId":"An::barge",…}]}
```

--------------------------------

### Negative test case example

Source: https://opensysml.org/internals/architecture

Example of a negative test case for malformed input, expecting an error. Used in the TestNegative suite to verify graceful rejection of invalid syntax.

```go
{
    name: "unclosed_package",
    input: "package Foo {",
    wantError: true,
},

```

--------------------------------

### Debug Action Step-by-Step

Source: https://opensysml.org/reference/api

Creates an action executor and steps through execution, inspecting tokens at each step. Useful for debugging action behavior.

```go
// Or debug step-by-step
exec, _ := ctx.CreateActionExecutor(myActionSym)
exec.Initialize()
for exec.State() != StateCompleted {
    exec.Step()
    tokens := exec.Tokens()
    // inspect tokens
}
```

--------------------------------

### Maven dependency for opensysml-client

Source: https://opensysml.org/reference/java-api

Add this dependency to your Maven project to use the OpenSysML Java client. The version is a snapshot and not yet published, so you must install it locally with `mvn -f clients/java/pom.xml install`.

```xml
<dependency>
  <groupId>org.openmbee</groupId>
  <artifactId>opensysml-client</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>
```

--------------------------------

### Response example for opensysml/render

Source: https://opensysml.org/reference/lsp

Example response for the `opensysml/render` request. Shows the rendered view, kind, stated, form, and artifact. The `artifact` contains the Mermaid diagram. The response includes nodes, edges, notices, and version.

```json
{
  "view": "KitViews::widgetTree",
  "kind": "tree",
  "stated": "",
  "form": "mermaid",
  "artifact": "%% KitViews::widgetTree — tree rendering\nflowchart TD\n  n0[\"Kit::Widget<br>«part def»\"]\n  n1[\"cog : Cog<br>«part»\"]\n  n0 --- n1\n  …",
  "nodes": [
    {
      "id": "n0",
      "kind": "part def",
      "name": "Kit::Widget",
      "type": "",
      "detail": "",
      "origin": {
        "uri": "file:///tmp/kit.sysml",
        "range": { "start": { "line": 1, "character": 1 }, "end": { "line": 6, "character": 1 } },
        "selectionRange": { "start": { "line": 1, "character": 10 }, "end": { "line": 1, "character": 16 } }
      }
    },
    {
      "id": "n1",
      "kind": "part",
      "name": "cog",
      "type": "Cog",
      "detail": "",
      "parent": "n0",
      "origin": { "uri": "file:///tmp/kit.sysml", "range": { "…": "…" } }
    }
  ],
  "edges": [{ "from": "n0", "to": "n1", "label": "", "kind": "connection" }],
  "notices": [],
  "version": 7
}
```

--------------------------------

### Captured JSON for each Value arm

Source: https://opensysml.org/reference/wire-contract

JSON objects showing the captured representation of each Value arm as returned by Evaluate. Each object has exactly one key, the arm name, and the value is the arm's payload. The examples are taken from the table and show the JSON type and structure for each arm.

```json
{"result":{"intValue":"4"}}
```

```json
{"result":{"realValue":0.3333333333333333}}
```

```json
{"result":{"boolValue":true}}
```

```json
{"result":{"stringValue":"abc"}}
```

```json
{"result":{"instanceId":"2"}}
```

```json
{"result":{"sequence":{"elements":[{"stringValue":"nav"},{"stringValue":"sci"}]}}}
```

```json
{"result":{"null":""}}
```

```json
{"result":{"quantity":{"realMagnitude":5.4,"unit":"SI::km/SI::h","unitTerm":{…}}}}
```

```json
{"result":{"enumLiteral":{"literalId":"Rover::Mode::idle","enumerationId":"Rover::Mode","name":"Mode::idle"}}}
```

```json
{"result":{"unset":true}}
```

```json
{"result":{"complex":{"real":1.5,"imaginary":-2}}}
```

```json
{"result":{"array":{"dimensions":["2","3"],"elements":[{"intValue":"1"},…,{"intValue":"6"}]}}}
```

```json
{"result":{"vector":{"components":[{"realValue":3},{"realValue":4}]}}}
```

```json
{"result":{"vectorQuantity":{"components":[{"realMagnitude":3,"unit":"m","unitTerm":{…}},…]}}}
```

```json
{"result":{"measurementRef":{"unit":"m","unitTerm":{…},"unitId":"SI::metre"}}}
```

```json
{"result":{"infinity":true}}
```

```json
{"result":{"function":{"calcId":"F::Sq"}}}
```

```json
{"result":{"set":{"elements":[{"intValue":"1"},{"intValue":"2"},{"intValue":"3"}]}}}
```

```json
{"result":{"tensorQuantity":{"dimensions":["2","2","2"],"components":[{"realMagnitude":1,"unit":"m","unitTerm":{…}},…]}}}
```

```json
{"result":{"metaobject":{"elementId":"Meta::seatBelt","metaclassId":"SysML::Systems::PartUsage"}}}
```

```json
{"result":{"undetermined":{"reason":"P::Q::d has no value in the model","count":{"lower":"1","upper":"1"}}}}
```

--------------------------------

### CLI checks with -instantiate, -constraint, and -satisfy

Source: https://opensysml.org/guide/03-command-line

Command-line invocations and their outputs. The first shows -instantiate and -constraint flags; the second shows -satisfy. Both demonstrate that -instantiate always runs first and that verdicts apply to the created object.

```bash
$ sysml -instantiate MyModel::cold -constraint MyModel::cold::inRange checks.sysml
✓ package MyModel
✓ Created instance of MyModel::cold
  ID: 1
  Use %features MyModel::cold to inspect
✓ Constraint MyModel::cold::inRange passed (on MyModel::cold ID: 1)
  standing: holds (observed: 1 run under reverse)
```

```bash
$ sysml -satisfy checks.sysml
✓ package MyModel
✓ satisfy healthy by cold holds (on MyModel::cold ID: 1)
  standing: holds (observed: 1 run under reverse)
✗ satisfy healthy by hot fails (on MyModel::hot ID: 2)
  Required condition evaluated to false: sensor.reading <= sensor.threshold
  standing: violated (witnessed: 1 run under reverse)
```

--------------------------------

### Open an action session and advance time

Source: https://opensysml.org/guide/06-behavior

Opens an action session for Q::Main, then advances time to dispatch the accepted message. The output shows the action state and the number of steps taken.

```sysml
sysml> %action Q::Main
✓ Started action executor for "Q::Main"
  State: Running
  Tokens: 1

sysml> %advance 0
✓ Advanced to 0.0 (0 event(s) processed)
  Action state: Waiting
  Tokens: 1
  Action steps taken: 5
```

--------------------------------

### Start state machine executor for Timed::listener

Source: https://opensysml.org/guide/06-behavior

Starts the state machine executor for the listener state. The output shows the current state is idle, time is 0.0, and events are 0. It suggests using %events, %current, and %advance.

```sysml
sysml> %state Timed::listener
✓ Started state machine executor for "Timed::listener"
  Current state: idle
  Time: 0.0
  Events: 0

Use %events to see queue, %current for state, %advance <time> to step
```

--------------------------------

### Request example for opensysml/render

Source: https://opensysml.org/reference/lsp

Example request body for the `opensysml/render` request. It specifies the document URI, the view to render, and the output form. The `view` can be omitted to use the document's declared view, and `form` can be `mermaid`, `text`, `markdown`, `dot`, or `plantuml`.

```json
{
  "textDocument": { "uri": "file:///tmp/kit.sysml" },
  "view": "KitViews::widgetTree",
  "form": "mermaid"
}
```