Download arche-lang

Simpler to write — traces where they start: verifies REQ-1 as t-7 (a trace property keeps its id), trace satisfies A -> R1 as s-1, R2 (several targets), verifies on a scenario, and the traces of a requirement written inside a component. archec move-traces moves each trace written apart to where it starts, writing out positional ids and address strings as paths, only if the same traces come out — kacao: 721 traces moved. archec diff compares traces.yaml by id.

Simpler to write — attr escapes as syntax: function-flow A -> B "item" as fl-1 { name "…" }, port-type latency/jitter/bitrate and memory-mapped, link bus; a part that shows another model (ref) is walked into by paths, so a scenario's attr participants/attr sequences become participant/sequence (fmt --simplify) — kacao: 72 escapes gone, scenarios.arche 5,748 → 2,650 lines.

Simpler to write — readable names: component flash_memory "FLASH_MEMORY" as c-1793752253957: paths say the name, Arche keeps the id. archec name-components names imported ids from their labels — kacao: 11 components, 527 → 39 ids left (the as ids and Arche address strings).

Simpler to write — translations apart: translations en { REQ-1 "Start"; REQ-1.text "…" }, the same as en "…" after each text; archec translations --extract en moves the inline ones into one file, only if the project builds the same.

Simpler to write — cases as a table: cases "Speed {v}" { body; rows { id | v; TC-1 | 10 } }, a case per row (- leaves out the lines that use a cell) — kacao's PBIT decision table: 32 cases, 512 → 52 lines.

Simpler to write — quick fixes that declare: an unknown message, type, port type, requirement, component… is declared at the end of the file; a link to a missing port adds it (direction from the end, type from the other end).

Documentation: a tutorial (docs/tutorial.md) that builds a water pump from model to firmware, and is compiled by the tests; every command in docs/commands.md; an index, docs/README.md.

archec ci: lint (with the project's rules and suspect links), format, timing, TARA, build, tests and coverage (--coverage-min) in one command, one line per gate, a JUnit report (--junit), exit 1 when a gate fails.

Versioned libraries: a library is a folder with a library.arche (library kria-parts { version "1.4.0"; archec ">=0.10" }), side by side as <name>@<version>/; uses kria-parts "^1.4" takes the newest in range and include "kria-parts/…" reads that version; archec lib lists, archec lib lock writes arche.lock. Missing, out-of-range, too-new-for-archec, conflicting, unlocked and changed-under-lock libraries are pointed out.

Embassy state machines: a part's state machine in Rust (states, events, the transitions innermost first, * -> X, guards as methods to implement, goto_name), fired by its task when a trigger message arrives, with on_transition for the action; a new app.rs has the part's variables at their initial values and the model's Python under each TODO.

Works without ../arche: the Arche code archec runs (RTOS generator, rule engine, study evaluation) is one minified bundle committed as vendor/arche.js (1.4 MB, for 6.9 MB before).

One version: archec --version, package.json and the extension all say 0.10.0.

Inside: checker.ts and emit.ts split by topic (src/checker/, src/emit/), the compiler tests by area; the same diagnostics and byte-for-byte the same builds.

Debugger variable values: arche-cli --trace also writes the trace records (PLAN__CASE.trace.json), so a debug session over a run shows each component's variables. An older arche-cli still works, without values.

ARXML system description: ECU instances (one per processor, with CAN connectors and frame, PDU and signal ports), PDU and signal triggerings, the SYSTEM with its root composition, the SWC-to-ECU mapping, and the data-element-to-signal mapping (signal groups, field by field).

Embassy CAN FD on STM32: a chip with FDCAN (stm32g4, h7, h5, l5, u5, g0b…) gets an FDCAN driver in src/can.rs: CAN FD frames up to 64 bytes with bit-rate switching, so the car's 15-byte BRAKE_CMD goes out (padded to 16); these chips build with embassy-stm32 0.2, executor 0.7, time 0.4. On a bxCAN chip, the note names each message longer than 8 bytes, and can::DROPPED counts the frames not sent, instead of losing them silently.

Embassy CAN on ESP32: hal esp32 gets a TWAI driver in src/can.rs (TWAI0, the nearest preset rate). nRF and RP2040 get a note that they have no CAN controller.

Guards in UPPAAL and NuSMV: a guard on the component's own variables is translated. A variable that the machine's transitions set to written values becomes a small integer. Of one state's transitions on one trigger, the first that can fire wins. NuSMV uses a TRANS relation.

Cybersecurity (TARA, ISO/SAE 21434): asset, damage-scenario, threat, attack-path, security-goal; feasibility, risk and CAL derived; checks; archec tara; a LaTeX section; goals as Arche requirements of category security.

Error propagation (the idea of AADL's error model): a port says the errors its part makes there (produces omission, value), stops (contains late) or changes (turns value into omission), and which inputs feed an output (from, from-all for redundancy); hazard … { error omission on Car.brakes.cmd }. archec derives each hazard's fault tree, its minimal cut sets and rate, and an FMEA row per error source, checks them against the written ones (fta-mismatch, fmea-mismatch) and shows them, marked derived, in archec safety, the LaTeX and HTML specification and the Safety group of the model tree.

STPA: control-action CA-… { from Car.adcu; to Car.brakes; feedback …; uca UCA-… { type not-provided; causes HZ-…; constraint REQ-…; loss-scenario LS-… { … } } } — the architecture is the control structure. Checked: each control action considered for the four types or said not-applicable (stpa-incomplete), each UCA traced to a hazard and a constraint (uca-untraced), a link that carries the action and its feedback (stpa-no-path); the tables in archec safety, the LaTeX and HTML specification, and the model tree (Control actions (STPA), a UCA under its type).

FMUs in the simulation: archec import plant.fmu, a component's fmu "plant.fmu", copied into the project and co-simulated by arche-cli (FMI 2.0 CS, Real, Integer, Enumeration and Boolean variables, a native host; sources built with cc when no binary).

Test coverage: archec test --coverage, Run with Coverage in the Test Explorer — states, transitions, messages per link, functions and requirements the runs exercised, marked at their lines (arche-cli test --coverage).

Fault injection in tests: at 20ms fault drop a.p / delay / stuck a.p f=0 / freeze part / thaw / clear, or a failure mode's id (its new inject), run by Arche's simulation (new engine fault helpers).

Timing analysis: handler-blocking — a message handler on a periodic thread that can hold the step past its deadline (counted as blocking in the response time, shown in the thread's hover).

Exporters for the tools around the model (archec gen --target …): aadl, an AADL v2 package of the deployment for OSATE (processors with a virtual processor per core, the bus, processes and threads with Dispatch_Protocol, Period, Deadline, Compute_Execution_Time, Priority and Stack_Size, ports typed by Data_Model data, connections bound to the bus and processes bound to their core); arxml, AUTOSAR Classic R4 (implementation data types, a sender-receiver interface per message, a software component per part with runnables on timing, data-received and init events, the composition, and per routed message on a CAN bus the I-signals, I-PDU, frame and CAN id); bom, a bill of materials as CSV and Markdown, grouped by definition with quantity, mass, power, cost, ram and every budgeted number, with totals and a roll-up per subsystem; icd, an interface control document per port type, interface and bus: the messages with their fields, units, ranges and byte layout, the links that provide and consume them, their timing and CAN ids, and the requirements traced to them.

One way to write each thing. Each declaration has one standard keyword, and multi-word ones take a hyphen: port-type, test-plan, use-case, joining failure-mode and safety-goal. The other spellings are still read and build the same project. Each gets an alias-keyword hint with a quick fix, and fmt --simplify rewrites it. That covers msg, req, let, regs, ivv, adr, contract, namespace, record, block, connect, statemachine, function, task, interrupt, firmware, param and the rest. A word now means one thing:

• bus X declared a port type, but a route's bus is a component with kind bus: write port-type X.
• process is an OS process in a deployment; a workflow is a workflow.
• mode is an operating-mode, not a state; view and model are properties, not keywords.
• A pseudo-state is pseudo choice, since kind names a catalog kind.
• A requirement's provenance is origin, since source is where code lives.
• A processor/device with a kind is a component: the kind makes it hardware.

Same thing, one form. attr key = value, like prop key = value (the = may still be left out). private fn f instead of visibility private. struct D extends Base and interface I extends J in the header. lanes "a.*", "b.*" without brackets. complexity medium in lower case (Arche still gets Medium). A parameter takes range 1..8 for its min/max, and a safety goal's ftti is checked as a time. The importer writes the standard forms. The four examples are converted, and they build byte-identical projects.

unit m/s², unit °C, unit km/h: a unit is written as it is, to the next space, and reaches Arche unchanged. The quoted form is still read; it's needed only for a unit with a space, and fmt --simplify drops the quotes. The examples are converted and build the same projects.

processor and device are just component. The keyword alone no longer makes a block hardware for the deployment checks: its kind (processor, device, sensor…), cores or nature hardware does. fmt --simplify writes component Soc { kind processor; … }, adding the kind the keyword implied. This is the one rewrite that changes the generated project, which gains that kind:. A device x: Lidar instance becomes part x: Lidar.

component LidarFront extends Lidar { … } builds a definition on another. It has the base's kind, ports, functions, variables, parameters and state machine; what it writes adds to them or replaces them by id, and its states { … } adds states and transitions to the base's (the base's initial state stays unless it names one). Arche has no inheritance, so templates.yaml and every part carry the whole of it. extends on a part, and a definition that extends itself, are errors. component A : B at top level used to drop B's members silently; it now means the same and gets a hint with a quick fix to write extends.

The project's rules are checked in the editor. rule sw-on-cpu "…" { applies component; when kind == "software"; check parentKind in ["processor", "software"]; severity error; message "…" } was already written to rules.yaml for Arche's Problems view. Now archec runs it with Arche's own rule engine (bundled from the app, so the verdicts are the same) and reports each breach on the element where it is written, with the rule's severity. A breach doesn't stop the build. A condition that doesn't parse is an error on the rule. when and check are written without quotes, applies is a name, and severity and disabled are properties, so attr severity is no longer needed. The quoted form is still read, and fmt --simplify unquotes it. kacao's rules report 240 infos, mostly requirements with no test.

fix: optional GpsFix is a field that may be absent: it is written to Arche as multiplicity: 0..1, and archec gen embassy makes it an Option<GpsFix>. fmt --simplify rewrites { multiplicity 0..1 } to this form. optional on a variable or an argument is an error.

union Command { stop; move: MoveArgs; speed: float32 } holds one of its cases. A bare name is a case with no payload; name: Type is a case that carries a value. Arche has no union type, so it gets the enum CommandCase of the cases and a struct Command with a case field plus one 0..1 field per payload. Messages built from it show and simulate as usual. archec gen embassy writes a Rust enum Command { Stop, Move(MoveArgs), Speed(f32) }, whose default is its first case. On a bus, an optional field is a presence byte plus its value, and a union a case byte plus room for its largest case, so the Embassy codec encodes and decodes them and the DBC frame multiplexes on the case.

System operating modes, written as the model names things. An operating-mode now names its components and requirements as the rest of the model does: components kria.ps, imu (from the top of the one system that has them, or KaCAO.terminal) and requirements REQ-KAC-010. Arche gets the same addresses as before. Transitions are to STANDBY on PBIT_RESULT_OK when "every PBIT passed", replacing attr transitions [...]. An unknown target mode is an error, and a second initial mode is a warning. budget power 60W in a mode adds up the components active in it (all of them when it names none) and says when they draw more; archec checks this, since Arche has no per-mode budget. fmt --simplify rewrites the quoted addresses and attr transitions; kacao's 7 modes now read this way, with the same built project.

Tolerances. parameter VBUS { value 12; unit V; tolerance 5% } (also tolerance 0.5, tolerance 20us, tolerance -2%, +10%) is written to Arche as the parameter's min/max, so its slider and sweeps keep to the band. distribution normal makes the tolerance 3σ (the default is uniform). A study with worst-case sweeps both ends of every toleranced parameter its outputs read (or those it names), and Arche evaluates each corner. archec study main.arche <id> runs a study with Arche's own evaluator, bundled from the app: a worst-case study gives each output's lowest and highest value and the corner where it occurs; monte-carlo 2000 (with seed) gives the mean, σ, the 5/50/95 % percentiles and the range of 2000 random designs. Arche has no random-sampling study, so it shows a Monte Carlo study at the nominal values. Studies now write their seed to Arche.

ReqIF, both ways. archec reqif main.arche -o reqs.reqif writes the requirements as ReqIF 1.2, the format DOORS, Polarion, Jama and codebeamer exchange. Each requirement carries ReqIF.ForeignID, ReqIF.Name and ReqIF.Text (as XHTML), plus status, priority, verification method, rationale, source, owner, tags and TBC, with translations as Name (en) / Text (en). There is one specification per document, and derives links become relations; --document SRS exports one document. archec reqif reqs.reqif -o reqs.arche reads one back: attributes are matched by name (a tool's "Object Text" or "Description" is the statement, "Object Heading" the title, enumerations by value name). The documents become deliverable declarations, and what has no place in the language is kept as a comment. kacao's 513 requirements go out and come back in with no errors.

SysML v2. archec sysml main.arche -o model.sysml writes the architecture in SysML v2 textual notation:

• definitions as part def (extends as :>) and parts as part;
• ports typed by a port def per port type, with ~T for in ports;
• links as connect, variables as attribute, state machines as exhibit state;
• structs and unions as attribute def, enums as enum def, messages as item def;
• requirements as requirement <'R-1'> with their text as doc, and satisfies as satisfy … by part.

Deployment, the canvas and Python behaviour are left out.

SysML v2, in. archec import model.sysml -o model.arche reads a SysML v2 textual model into arche-lang, then builds the result and reports its errors. Part defs and parts (with [4] and :>), ports with ~ and the items of their port defs, item, attribute and enum defs, attributes with = 1200 [kg], interface defs, connect, connection and flow, state machines (with the short accept … then form and entry/exit/do), actions as fns, and requirements with <'id'>, doc, satisfy and verify are all mapped. The rest stays in the file as // sysml: … comments, with a note for each. The car, exported to SysML and imported back, gives back the same SysML text.

FMI 2.0. archec fmi main.arche Plant -o plant --build makes a co-simulation FMU of a system's (or a definition's) equations, for Simulink, Dymola, OpenModelica or any FMI 2.0 tool:

• each part's variables and ports go in, with links summed into the input they feed, and constants and parameters inlined;
• an unlinked in port is an FMU input, out ports and integrated variables are outputs, and a variable no equation gives is a tunable parameter;
• the solver is RK4 at the solver step;
• --build compiles it with cc and zips Plant.fmu.

The C source declares the FMI types itself, so it needs no SDK. The two-tank example's FMU passes fmpy's validation, and its simulation matches the example's own test (0.7225 m at 600 ms). Python behaviour does not go in.

Baselines and suspect links. archec baseline main.arche --name v1.0 freezes the requirements into baselines/v1.0.json beside the model, to commit with it. The baseline holds what each requirement says (title, statement, translations, metric, limit) and the traces pointing at it. Once a project has one, the linter compares against the newest. When a requirement's wording has changed, each test plan, case or element that verified or satisfied it gets a suspect warning where it is written, until it is re-checked and a new baseline is taken. A change of status, priority or owner is listed, not flagged. archec changes main.arche [--since v1.0] lists the requirements added, removed and changed (showing the part of a long text that differs) and the suspect links.

The specification as a web page or Markdown. archec doc main.arche -o spec.html (or --html) writes the specification as one self-contained page, and -o spec.md (or --md) as Markdown. The chapters are the LaTeX export's, plus operating modes:

• requirements as cards grouped by document, with status and priority, rationale, and what satisfies and verifies each one (marked when nothing does);
• data types and messages, and the architecture part by part (ports, variables, state machine, links);
• scenarios and test plans;
• a traceability matrix that counts the gaps, and the changes since the last baseline with their suspect links.

Requirement ids and [REQ-1] references are links. The page has a table of contents, light and dark themes, and prints cleanly. LaTeX math is typeset by KaTeX when the page can load it.

Inlay hints. After the value or declaration they are about, they show what archec computed:

• a sum of quantities as one value (2 * TICK + 500us = 2.5ms), a rate as its period (2.5kHz = 400us period), a constant's value where it is used;
• the ports a definition inherits (extends Lidar inherits ports cloud, power);
• a budget's roll-up against its limit (= 8.5W of 10W, ⚠ 12W of 10W), the same sum the checker makes;
• a deployment thread's worst-case response time and deadline (R=200us/D=1ms), from the timing analysis;
• the copies of a part array whose size is a constant (= 4 parts).

A plain quantity gets none. arche.inlayHints.enabled turns them off.

Semantic highlighting. The language server colours each name by what it resolves to. A definition is a class, a part a read-only variable, a port a property, a message a type, a requirement a requirement, a state an enum member, a function a function, a constant a read-only variable, a deployment a namespace, a thread an event. A quantity's unit is a unit token. The TextMate grammar still colours keywords, strings and numbers.

A simulation debugger. A test case runs in simulation with arche-cli (test --case … --trace), and you step through its run event by event. Start it with "type": "arche" in launch.json (program, case), F5 on an .arche file, or Debug Test on a case in the Testing view.

• The stack frame is the event, at its line in the model: a message at the function it ran on arrival (or the transition it fires, or the case line that sent it), a state change at the state, an expectation at its expect line.
• Variables shows the time, the event, each component's state, the expectations checked so far and the messages sent. Watches and hovers read time, adcu.state and sent("X").
• Breakpoints go on .arche lines, and a failed expectation or an error stops the run.
• Step over goes to the next event and step out to the next instant. Step back and reverse continue work too.

arche-cli's trace has no variable values; "trace" replays one exported from the Arche app, which has them. arche-cli keeps the run of a failing case only, so the debugger builds a copy of the project and adds a last step that fails on purpose. That step is hidden, and the case's verdict is reported as it is.

• State machines are walked as graphs, bases included. unreachable-state now follows composite entry and ignores transitions that never fire. New checks: deadlock-state (a state with no way out that is not pseudo final), dead-transition (a message no input port receives, a false guard), shadowed-transition (beaten by an earlier unguarded one on the same trigger), and nondeterministic (a hint for two guards that may both hold).
• contract { assume cmd.force in 0..1000N; guarantee status.applied within 20ms after cmd } on a component, an interface or a port type. At each link the sender's guarantees must imply the receiver's assumptions: ranges and equalities on the same field, and deadlines. The checks report contract-unmet and contract-unknown. Contracts stay in the model (Arche has no place for them), and archec sysml writes them as assume / require constraints.
• archec gen --target uppaal writes UPPAAL timed automata and queries (no deadlock, each state reachable, each within kept). --target nusmv writes untimed SMV modules.

• Message fields take their default when a message is built without them, and a struct field is built from its fields' defaults (BRAKE_CMD(force=1.0) carries a whole header).
• Test cases can be a timeline (at 5ms do …, at 10ms expect …, within 40ms expect …). Each moment starts at its time from the start of the case.
• fmt --simplify puts kind, layer, tags and color on one line.
• duplicate-trace reports the same link written twice.
• duration-math suggests to_s(X) for X / sec(1).
• Test-step linting finds a block by its id at any depth, as Arche does.