Analyse
The commands that analyse a model and the running system: timing, model checking, safety, security and logs.
Commands: archec analyze · archec timing · archec verify · archec why · archec why-not · archec replay · archec live · archec study · archec safety · archec tara · archec parts · archec merge · archec observe · archec cad · archec synth
On this page: More on these commands
| Command | What it does |
|---|---|
archec merge <base> <ours> <theirs> [--path p] [-o out] |
A three-way merge of .arche files by declaration, as git's merge driver: what one side changed is taken, a declaration both changed is merged inside (its properties by key, its members by kind and name), and only an item both changed differently is a conflict, marked with its name (<<<<<<< ours: Brake.pressure). A side that does not parse is merged line by line. archec merge --install writes *.arche merge=arche to .gitattributes and sets the driver in the repository's git config. Exit 1 on a conflict. |
archec verify <main.arche> [-o dir] [--json] |
The model checker (NuSMV or nuXmv, on the PATH or named by NUSMV) on each requirement's formal property — never brakes in Fault, always …, eventually …, a in X leads to b in Y — and on each state's reachability. A property that fails comes with its counterexample as a sequence diagram (<REQ>.mmd). Exit 1 when one fails, 2 when no checker is found. archec ci runs it as its verify gate. NuSMV is untimed: a within is left to the monitors, archec replay and --conflicts. Each property proved or refuted is recorded as evidence for archec status (--no-record: not). |
archec verify <main.arche> --conflicts [--tick 10ms] [--horizon 8] [--json] |
Requirements no implementation can satisfy together (realizability, as NASA's FRET checks it), with nothing to install: the formal properties and the EARS sentences, read over each part's states. The environment chooses the message each part receives at each tick (one, or none); the implementation then chooses each part's state, any of them (the machine's transitions are one implementation, not a limit), from its initial one. A set no choice of states survives is a conflict: printed as a minimal set (leave out any one and the rest can hold), with a witness — the inputs tick by tick, the obligations awaited, and at the last tick every state left with the requirement it breaks (req-conflict). Bounded: time is counted in ticks (the deadlines' common divisor, made coarser — each deadline rounded up — past 16 ticks per deadline; --tick sets it); eventually and leads to with no within are read as within --horizon ticks (8), so a conflict that names one may go away with a longer horizon; an EARS response with no within comes at the tick of its trigger; a response that sends a message is not read; orthogonal regions are read as one; a group of requirements whose game has more than 2 million moves is not solved (a note says so). Requirements that share no part are checked apart. Exit 1 on a conflict. |
archec verify <main.arche> --meaning [REQ…] [--json] |
What each formal property (or the one an EARS sentence gives) says: a sentence, and two small timelines, one where it holds and one where it fails, as NASA's FRET draws them. archec doc --html and --md show the same under each requirement. |
archec verify <main.arche> --modelica [--system S] [--results S_res.csv] [--case TC] [--tol 0.01] [-o dir] [--json] |
Each system with test plans, as gen --target modelica writes it, simulated by OpenModelica (omc on the PATH, or OMC=…; the package and the results in <dir>/modelica/), its test plans' expectations read on the results (at, within, never:, always:, a step's expect at 1s: …; the network's names or Arche's physics.x_y), and archec physics run on the same network beside it: each state's largest gap against --tol of its span. --results: a run made elsewhere (OpenModelica's CSV, or any with the time first and a column per variable by its Modelica or network name). Exit 1 when a case fails or the two disagree, 2 with no OpenModelica and no --results. See physics. |
archec why <main.arche> (--test <case> | --trace <file> | --for 10s) ["<event>"] [--json] [--all] |
A run explained (see why.md). The run is a test case on archec's simulator (--test), a trace (--trace: the arche-trace lines or Chrome JSON of archec gen --target c|embassy --trace, or archec sim --json), or a plain run (--for). With no event, its timeline: the messages (a repeated one folded), each state change with its transition, model line and the values its guard read, the variables, the test's expectations when each was decided and the requirements checked on the run. With an event — a state ("fan Running"), a message ("ctl sends FAN #2"), a port (ctl.fan last), a variable ("air.temperature at 1s") — its causes back to the root: the transition, the guard and its values, the message and where in the model it is sent, the thread that sent it, the variable or the test behind the value, each with its file:line, time and the time between links; how long it took from the reading, and each requirement that bounds that delay (EARS within, or a within in the text of a requirement a part of the chain satisfies), held or not. On a trace, what caused what is found from the model and the order in time. Exit 1 when the event is not in the run. |
archec why-not <main.arche> (--test <case> | --trace <file> | --for 10s) "<transition or event>" [--json] |
Why a transition ("Cooling -> Idle", "ctl Cooling -> Idle on READING"), a state ("fan Running") or a message never happened: its source state was never active (and why the ways into it were not taken), its trigger never came while it was (and who should have sent it: a port linked to nothing, a sender that never sent), or its guard was never true (and the closest its values came: "the lowest celsius was 26.3 °C"). On a trace with no values (no value records) it says that it cannot tell. |
archec replay <main.arche> <log>… [--format f] [--deployment D] [--bus can0=<bus>] [--period-tolerance 50%] [--json] [--junit report.xml] [--strict] [--events] [--scenario out.arche [--from part,…]] |
Runtime verification: the real system's logs checked against the model. It reads candump (default and -L), Vector ASC and BLF, ROS 2 MCAP (chunks stored, lz4 or zstd), JSON lines ({"t", "msg", "from", "value"}, or {"t", "part", "state"} for a part's state) and distributed traces (OpenTelemetry OTLP JSON, Jaeger, Zipkin: each call from one service to another is a message, by the name archec observe gives it or its label); several logs are one trace. A CAN frame is the message its deployment's route gives that id, decoded by the layout the DBC and the generated C and Rust share; a ROS 2 message is decoded by its type (CDR, as --target ros2 writes the .msg). Then each check, with the time of its first violation: EARS requirements as monitors (the trigger, the while, the response within its deadline), formal properties (never, always, implies, leads to, eventually, and their within), a metric that is a message field against its limit, contracts (assume, guarantee … within 30ms after M), chains' budgets (the latest input taken as the cause: a lower bound), each field's range, each message's period (± 50 %), each port's stale-after. What reads a state needs the states in the log, else it is not checkable; a response the log ends before is inconclusive (--strict fails on it). JUnit like archec ci. --scenario out.arche writes the log as a test case for the simulator: what the parts --from names sent (default: the parts with no state machine), sent to the model at the times it came, and each state the log gives after the first, expected; include it and archec test shows where the model does not do what the system did. Exit 1 on a failure, 2 when a log cannot be read. Each requirement checked is recorded as evidence for archec status: --board <id> or --place renode says where the log came from, --firmware <file> what ran (--no-record: not). A firmware's trace says which build it is in its first line (the build a board runs): one of this model's build is kept in the record; one of another build is said first — the board runs an older build: rebuild and flash — nothing is recorded and the exit is 1 (--any-build: judged anyway). |
archec observe <trace>… [--states] [-o observed.arche] [--model main.arche] [--json] [--format otlp|jaeger|zipkin] [--system Name] [-k 2] |
How the running system behaves, recovered from its traces: OpenTelemetry's OTLP JSON (the file exporter's lines, or one object), a Jaeger JSON export, Zipkin v2 JSON. A span whose parent ran in another service is a call from that service to its own (the server span's name, the time from the client span's start to its end); a client span with nothing under it goes to its peer.service, db.system or server.address; a span in the same service is one of its steps (an fn). Writes a .arche (-o, else to stdout): a message per operation (POST /orders → POST_ORDERS, a gRPC Svc/Charge → CHARGE), a component and a part per service (outside sends what starts a trace), a link per caller and callee with each operation's count, p50, p95 and errors, and its latency the time on the wire; a scenario per way a request went (the traces clustered by the shape of their calls: calls that overlap are a par, the same call in a row a loop), with how many traces went that way and each reply's p50 and p95 or its error. --states: a state machine per service that waits on another, from what it received request by request (the request, then each reply), its states named by the replies they await, merged when they await the same and the next -k events are the same (k-tails); a // observed: comment says in how many traces each transition was taken. The file checks and draws (archec diagram <file> <scenario>, <System.part>.states). --model main.arche: the traces against a model instead — services no part is, calls no link or message of the model is, links never seen, a link's deadline against the time on the wire, a timeout against the replies, and what archec replay checks (EARS, formal, periods) on the calls as messages. --json for CI. Exit 1 when the model misses something or a check fails, 2 when a file has no span. |
archec analyze <main.arche> [--json] |
Each deployment's timing: core loads, response times against deadlines, bus loads, memory, end-to-end chains. Exit 1 when a core is overloaded or a deadline or a chain budget can be missed. |
archec timing <main.arche> <trace…> [--deployment D] [--json] [--junit report.xml] [--html report.html] |
What a run did, beside what archec analyze predicted. The traces are those archec gen --trace makes — arche-trace <ns> <kind> <name> <arg> lines from a UART, defmt or a log (anything before arche-trace on a line is skipped), or Chrome trace JSON — or any Chrome trace whose slices are named after the model's threads, or are the outermost on a thread so named. Per thread: activations, period and jitter, response time from its release (min / avg / p99 / max) and the time it ran, preemption taken out; per core: the share of the trace its threads were active; per bus: the load of the frames sent on it; per chain: the latency from a start to its end. A measurement worse than the prediction is flagged OPTIMISTIC (the analysis is wrong: a wcet too small, a blocking it does not see), one over a deadline or a budget MISS; either exits 1 (2 when no event matches the model). --junit: a test case per thread, core, bus and chain, as archec ci writes them; --html: one self-contained page. An event thread's response counts from when it starts; a chain whose start and end are in two traces takes their clocks as one. What the traces say of each requirement (its chains, threads and monitors) is recorded as evidence for archec status: --board <id> or --place renode says where they were taken, --firmware <file> what ran (--no-record: not). A firmware's trace says which build it is in its first line (the build a board runs): one of this model's build is kept in the record; one of another build is said first — the board runs an older build: rebuild and flash — nothing is recorded and the exit is 1 (--any-build: judged anyway). |
archec live [main.arche] [--deployment D] [--replay <trace|dir>…] [--json] [--once] [--duration 10s] [--html report.html] [-o dir] [--no-compose] |
The living model: what a running system does turns the model's requirements, chains, threads and containers pass, fail or pending as it runs. Without --replay, the deployment's containers (the one --deployment names, else the first with containers) are generated (--target c --trace built with make LIVE=1, --target containerd, into -o, else a temporary folder), built with podman build, started with podman compose (plain podman run with --no-compose or without compose), their logs followed and podman stats polled every 2 s; the state is evaluated every second and the containers removed at the end (Ctrl-C, or --duration). --replay <file|dir>…: traces already written (arche-trace lines, a log with them in it, Chrome trace JSON), evaluated once. A chain or a thread fails on a miss (a budget, a deadline; worse than predicted only says so), a container over its memory-limit or stopped fails; a requirement fails when a runtime monitor says so (arche-trace <ns> monitor <REQ-ID> 1; an invariant, traced only when it fails, passes by its silence while other monitors report) or what satisfies it fails — a chain … { satisfies R }, a thread or a container running a part that satisfies R — passes when they pass, and is pending until then. Each state is also kept in .arche/live.json beside the main file (replaced whole at each refresh). --json: one state per line at each refresh (ndjson, nothing else on stdout), each item with its file and line; --replay may be given once per file; --once: run --duration (10 s), print the final state, exit 1 when anything fails; --html: the final state as one page. |
archec study <main.arche> <id> [--json] |
A study over the parameters' tolerances: worst case (each output's range, and the corner it is at) or Monte Carlo (mean, σ, percentiles). It runs Arche's own study evaluation (vendor/arche.js), not a simulator; to vary a parameter through a run of the network or of the behaviour, use archec physics --batch or archec sim --batch. |
archec parts [main.arche] [--provider nexar|digikey|mouser] [--offline] [--dry-run] [--json] |
Each part number of the bill of materials (product { vendor "…"; part-number "…" }), once, looked up at a distributor: its stock, its price breaks, its lifecycle (active, NRND, end of life), kept with the date in .arche/parts-cache.json. Nexar (Octopart): NEXAR_TOKEN, or NEXAR_CLIENT_ID + NEXAR_CLIENT_SECRET; DigiKey (Product Information v4): DIGIKEY_CLIENT_ID + DIGIKEY_CLIENT_SECRET; Mouser (Search API v1): MOUSER_API_KEY — the first whose keys are set, unless --provider; --url or ARCHE_PARTS_URL for another server. --offline: the cache only; --dry-run: the requests, keys left out, nothing sent. Exit 1 on a part at its end of life, NRND, out of stock or unknown. archec check then warns about those from the cache ([part-lifecycle], [part-stock]), with the date — only when the cache exists, and never on the network. Offline by default: archec config allow parts lets it ask the distributor (ai-engineering.md). |
archec safety <main.arche> [--json] |
The safety analysis: each hazard with its ASIL and its rate, written and derived; the fault tree of each hazard with error … on …, derived from the error model of the parts (produces, contains, turns, from), with its minimal cut sets; the FMEA derived from it — each error source, where its error goes, the hazards it leads to; the STPA — each control action by the four types of unsafe control action, the UCAs with their hazards, constraints and loss scenarios. Exit 1 when the derived and the written ones disagree (fta-mismatch, fmea-mismatch) or the STPA has a gap (stpa-incomplete, stpa-no-path, uca-untraced). |
archec tara <main.arche> [--json] |
The cybersecurity risk assessment (ISO/SAE 21434): each threat's impact, feasibility, risk and CAL. Exit 1 when a risk of 4 or 5 has no treatment. |
archec cad [main.arche] [--json] [--force] [--only <Name>]… [--no-run] [--python <exe>] [--html <page.html>] [--no-record] |
The geometry of the model, built and checked (CAD as code). Each component's cad "cad/part.py" file (build123d) that changed is run, and written to build/cad/ as STEP, STL and GLB. Its size, volume, mass (by its material or density), centre of mass, inertia and anchors are measured. Each system's parts are placed (at box.mount). The requirements' limits (limit Enclosure.mass <= 250g) and the clearances (clearance board, relay >= 2mm) are checked, and recorded for archec status. So are a board's mounting holes against the standoffs that hold it (fits board, box), the part numbers of what is bought (sourced Assembly), and KiCad's ERC and DRC of a board that names its pcb, when kicad-cli is installed (skipped, and said, when it is not). --no-run checks what is measured already, with no CAD engine; --force runs every file again; --html writes a 3D page of the result. The engine comes with the extension's platform builds, or is a Python that has build123d (ARCHE_CAD_PYTHON): archec never downloads it. |
archec synth [main.arche] [--device <name>] [--system <S>] [--deployment <D>] [-o <dir>] [--virtual-pins] [--bitstream [--constraints <pins.pcf|pins.lpf>]] [--seed <n>] [--json] [--verbose] [--no-record] |
The FPGA components synthesised, placed and routed for the device of the model (FPGA components): the chip of its kind fpga part (chip "iCE40UP5K-SG48", chip "LFE5U-25F-6BG381"), or --device. The generated VHDL is read into Yosys through GHDL, mapped to the device's cells and placed and routed with nextpnr. It says the LUTs, flip-flops, block RAMs and DSP blocks the design takes, and the highest frequency each clock can run at (fmax) against the one the model gives it. A requirement bounds them: limit Pwm.luts <= 500, limit Pwm.fmax >= 100MHz. What is measured is recorded for archec status (synth, a rung above ghdl). A top with more pins than the package has is placed with virtual pins. --bitstream writes the file to load (icepack, ecppack), with the pins of --constraints; flashing it is yours. The tools are in no build of the extension: archec synth --install-tools says where the pinned OSS CAD Suite is (about 500 MB; archec does not download it), and with --archive <file> checks the file against its sha256 and unpacks it in ~/.arche/fpga. Exit 0 it synthesises, meets its clocks and keeps its limits; 1 it does not; 2 it could not run. |
archec why-not <main.arche> <requirement | "Enclosure.mass" | "clearance board, relay"> [--json] |
Why a limit, a clearance or a fit on geometry is not kept: what archec cad measured, by how much it misses, and what would keep it. |
More on these commands#
While a system runs, archec live shows which requirements, chains, threads and containers pass or fail;
archec live-fix REQ-1 asks Claude why one fails — from the evidence, the measured and predicted timings
and the declarations involved — and proposes edits to the .arche files, each checked against the text at its
line. In VS Code, "Arche: Start Live" colours those lines, and "Explain & fix with Claude" previews the edits.
--dry-run shows what would be sent.
archec parts looks the bill of materials' part numbers up at Nexar (Octopart), DigiKey or Mouser —
stock, price breaks, lifecycle — and keeps the answers with their date in .arche/parts-cache.json;
archec check then warns about a part at its end of life, not recommended for new designs or out of
stock, from that cache alone.