Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,10 @@ needed, or download it for your desktop below.
Download the package for your platform from the
[Releases](https://github.com/schreck61/intersection-lab/releases) page: a universal DMG
for macOS, an MSI (or portable zip) for Windows on x64 and ARM64, and `.deb`, `.rpm` or
`.tar.gz` for Linux on x86_64 and aarch64. All are built and signed by GitHub Actions; see
[packaging/README.md](packaging/README.md) for how releases are made and verified.
`.tar.gz` for Linux on x86_64 and aarch64. All are built by GitHub Actions and come with a
signed build-provenance attestation, and the macOS app and the Windows executable and
installer are also code-signed; see [packaging/README.md](packaging/README.md) for how
releases are made and verified.

If you have a current Rust toolchain, you can instead build and install it from
[crates.io](https://crates.io/crates/intersection-lab):
Expand Down
33 changes: 19 additions & 14 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,14 @@ it, and what it doesn't protect against:
it has loaded.
* **No extra privileges.** Once installed, the app runs with your ordinary user rights
and never asks for more.
* **Only its own files.** The app reads trained-weights files: from a `weights` folder in
the folder it's started from, then from its folder in your user data directory, and
otherwise from the copies built into it. It writes them only when you save weights.
The `train` tool writes the weights it trains to a `weights` folder in the folder it's
run from, `bench` writes no files, and the app's screenshot mode (`TS_SHOT`) writes
only the image you name.
* **Only its own files.** The app reads trained-weights files: from a `weights` folder
in the folder it's started from, then from its folder in your user data directory, and
otherwise from the copies built into it. It writes them only when you save weights. To
draw its window, the desktop app also reads the fonts installed on your system and, on
Linux, desktop settings such as the mouse-pointer theme, and it loads the system's
windowing and graphics libraries. The `train` tool writes the weights it trains to a
`weights` folder in the folder it's run from, `bench` writes no files, and the app's
screenshot mode (`TS_SHOT`) writes only the image you name.
* **Files are checked before use.** A weights file is parsed into typed data, and its
network is checked against what its controller accepts (layer sizes, connections
between layers, finite values). A file that doesn't parse is skipped for the next
Expand All @@ -31,9 +33,11 @@ it, and what it doesn't protect against:
controller manage traffic badly, so use weights only from sources you trust.
* **No code from data.** The app has no plugins, scripting or other way to run code
from the files it reads, and its own code is safe Rust with no `unsafe` blocks.
* **Verifiable releases.** Every release file is signed and comes with a
build-provenance attestation (see [Verifying downloads](#verifying-downloads)).
Packages from anywhere else aren't covered.
* **Verifiable releases.** Every release package comes with a signed build-provenance
attestation. The macOS disk image and the app inside it, and the Windows executable
and installer, also carry their platform's signature (see
[Verifying downloads](#verifying-downloads)). Packages from anywhere else aren't
covered.

It doesn't protect against someone who can already change files in your user account,
who could replace the app or its weights, and a very large weights file is read whole
Expand Down Expand Up @@ -80,8 +84,9 @@ Out of scope: unrealistic simulation behavior or results. Those are welcome as o

## Verifying downloads

Every release includes `SHA256SUMS.txt` and a signed build-provenance attestation for
each file. To check that a download was built by this repository's release workflow:
Every release includes `SHA256SUMS.txt` and a signed build-provenance attestation that
covers each package and that checksum file. To check that a download was built by this
repository's release workflow:

```bash
gh attestation verify <downloaded-file> --repo schreck61/intersection-lab
Expand All @@ -92,6 +97,6 @@ pass it with `--bundle` to verify without fetching it from GitHub. The release's
`IntersectionLab-<version>.intoto.jsonl` is an identical copy, named the way supply-chain
scanners such as the OpenSSF Scorecard expect provenance to be.

The macOS app is also signed with a Developer ID and notarized, and the Windows
executable and installer are signed with Azure Artifact Signing. See
[packaging/README.md](packaging/README.md) for details.
The macOS disk image and the app inside it are also signed with a Developer ID and
notarized, and the Windows executable and installer are signed with Azure Artifact
Signing. See [packaging/README.md](packaging/README.md) for details.
6 changes: 5 additions & 1 deletion deny.toml
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,12 @@ confidence-threshold = 0.9
# this project. osv-scanner.toml ignores the same IDs for the OpenSSF Scorecard;
# remove an entry from both files once no dependency needs the crate (cargo-deny
# warns when an ignored advisory no longer applies).
#
# A locked version that has been yanked from crates.io fails the check too, whether
# or not an advisory exists for it. Update the crate, or, while no usable version
# exists, ignore it below as { crate = "name@version", reason = "..." }.
unmaintained = "all"
yanked = "warn"
yanked = "deny"
ignore = [
{ id = "RUSTSEC-2026-0192", reason = "ttf-parser is unmaintained, with no known flaw; only the Linux build uses it, for the Wayland window title (winit 0.30, sctk-adwaita, ab_glyph), and no winit 0.30 release drops it" },
{ id = "RUSTSEC-2026-0370", reason = "zvariant is unmaintained, with no known flaw, since it was merged into zbus 6; only the Linux build uses it, for AccessKit's screen-reader bridge, which still needs zbus 5" },
Expand Down
39 changes: 23 additions & 16 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -236,10 +236,10 @@ docs/ this document, insights.md, cooperative-intersections.md (wi
| `src/control/` | 8 | 1,608 |
| `src/rl/` | 3 | 361 |
| `src/gui/` | 5 | 4,905 |
| `src/bin/` | 2 | 693 |
| `src/bin/` | 2 | 727 |
| `src/lib.rs`, `src/main.rs` | 2 | 96 |
| `examples/` | 9 | 999 |
| `tests/` | 11 | 4,187 |
| `tests/` | 11 | 4,271 |
| `fuzz/fuzz_targets/` | 1 | 61 |

| Target | Built from | Purpose |
Expand Down Expand Up @@ -1776,7 +1776,7 @@ Hybrid's major/minor and T-intersection files hold only its best static tuning

| File | Lines | What it holds |
|---|---:|---|
| `src/bin/train.rs` | 441 | Training, model selection and the test report |
| `src/bin/train.rs` | 475 | Training, model selection and the test report |
| `rl/nn.rs` | 190 | `Mlp`, `Grads` and `Adam` |
| `rl/dqn.rs` | 166 | `Dqn`, `Transition`, `SavedModel` and `argmax_masked` |
| `rl/mod.rs` | 5 | The module list |
Expand Down Expand Up @@ -1985,7 +1985,8 @@ tuning.
### 8.5 `bin/train.rs`: training and model selection

`train [layout|all] [episodes] [episode-seconds] [dqn|hybrid|both]` trains on the
signalized layouts. The defaults are `all 200 900 both`; the README's commands train
signalized layouts. A name that matches no signalized layout stops it with an error
before it makes `weights/`. The defaults are `all 200 900 both`; the README's commands train
800 episodes of 900 s. It runs one thread per layout and controller, so `train all`
trains eight agents at once, and the private `Agent` enum wraps the two controllers
behind one interface. It moves the boxed controller into a `Sim`, runs an episode, and
Expand Down Expand Up @@ -2253,7 +2254,7 @@ flowchart TB
* **What happens when a check fails:** nothing is logged, and the next copy is tried,
so a damaged file doesn't hide a good copy further down the list. A Hybrid file
whose network doesn't fit still loads, without the network, since its base tuning
can still run.
can still run. A base tuning past the last of the 48 is read as the last one.

| The copy | Deep RL | Hybrid |
|---|---|---|
Expand All @@ -2269,11 +2270,15 @@ tuning". A Hybrid that loaded only a base tuning says "no network beat the best
tuning" when its file has no network, the same as for the shipped static files, and
"the saved network doesn't fit this layout" when the file's network was left out.

Saving goes through `save_path`. It writes to `weights/` in the working directory when
that directory exists, which, run from a checkout, overwrites the shipped files.
Otherwise it writes to the user data directory, creating it first, or to `weights/` when
there is no user data directory. `train` creates `weights/` when it saves, and the next
build embeds whatever it wrote.
Saving from the app goes through `save_path`. It writes to `weights/` in the working
directory when that directory exists, which, run from a checkout, overwrites the shipped
files. Otherwise it writes to the user data directory, creating it first, or to
`weights/` when there is no user data directory. `train` doesn't use `save_path`: it
writes only to `weights/` in the working directory, which it creates before it trains,
and stops with an error if it can't make the folder or write a file. Unlike `save_path`,
it doesn't turn to the user data directory when `weights/` is missing. It does write
over files of the same name already in `weights/`, including ones saved there from the
app. The next build embeds whatever `train` wrote.

A Hybrid file also records `base_score`, the validation person delay of what it
holds, when there is one. The app's *Save weights* measures no score, and when no
Expand All @@ -2295,9 +2300,9 @@ Weights files can be damaged or edited by hand, so their loading is tested and f
* `tests/weights_files.rs` checks that every shipped file loads, that seven kinds of
misshapen network are rejected (one with a weight of 10³⁹, which is infinite as an
`f32`), that a Hybrid whose network doesn't fit keeps its base tuning and says so,
that Hybrid files saved with a score that isn't finite load again, that a copy that
doesn't load is skipped for the next one and that networks whose outputs overflow
don't crash anything.
that a base tuning out of range is read as the last one, that Hybrid files saved
with a score that isn't finite load again, that a copy that doesn't load is skipped
for the next one and that networks whose outputs overflow don't crash anything.
* The `weights` fuzz target reads each input as both kinds of file for the
T-intersection. A file that is accepted gets a training step if it has a network,
then 20 s of simulation. The CI job "Fuzz (weights)" runs it for 60 s, starting from
Expand Down Expand Up @@ -3352,12 +3357,12 @@ release mode on Linux, macOS and Windows, and measures how much of the crate the
| `tests/cooperative.rs` | 14 | The cooperative crossing: no signals, sensors or crosswalks; its geometry and phase order; every gap policy safe under heavy demand, bursts, heavy vehicles and live switching; about 18,000 vehicles per hour served at the design demand, about 19,000 oversaturated and less with single left lanes or first come, first served; reproducible runs; light traffic barely delayed; emergency vehicles first; hand-placed vehicles crossing every way. Every run, except those of the no-signals, single-left-lane and reproducibility tests, must show no overlap between vehicle bodies, no zone entered while occupied, no box entry without a reservation, no step off a granted trajectory, no crossing inside its required gap and no line or zone time off its reservation (both to within a microsecond), and at least one crossing measured |
| `tests/failures.rs` | 20 | Failures at the cooperative crossing. When a vehicle stops dead at the worst moment, fail-safe gaps stop crossing traffic short of it under both schedules, mitigated gaps let it arrive at no more than 25 km/h and nominal gaps faster; a vehicle that brakes to a stop is survived; in batches a failure at a random place rarely reaches crossing traffic, though a dead stop is struck from behind; the crossing serves what a disabled vehicle leaves clear and recovers once it is cleared away; a failure outside the box only holds up its lane; a failure can be repeated at the same place on another run, and random failures are the same on runs with the same seed; twenty minutes of failures in heavy traffic leave nothing broken, and with fail-safe gaps no vehicles on crossing paths touch through some two hundred dead stops; a vehicle stopped in the box waits for one that passes it, one stopped behind a failure can fail in turn and one that fails at the edge of the map rolls off it; a failure only holds back the vehicles that leave their crossings for an emergency stop: none at rest is set going, none gets ahead of the trajectory it had, and one standing before its line loses its crossing instead; a vehicle that can't stop behind a dead stop is expected where it ends up, as is one that fails close behind it and one already on an emergency stop when the vehicle ahead stops short, and it stops by itself if the wreck is cleared away first; the log keeps the latest fifty failures; other layouts have none. Every run with a failure in it, except those of the test that repeats one, must show no vehicle off its trajectory, in the box without one, or overlapping another outside a recorded contact |
| `tests/pedestrian_rule.rs` | 4 | Deep RL's shield serves a crosswalk whose pedestrians have waited longer than `PED_MAX_WAIT`, longest wait first, and leaves shorter waits to the controller; the reward counts waiting pedestrians |
| `tests/weights_files.rs` | 6 | The shipped weights load, misshapen networks are rejected, a Hybrid without a fitting network keeps its base tuning and says so, Hybrid files saved with a score that isn't finite load again, a copy that doesn't load is skipped for the next one and networks that overflow don't crash (§8.7) |
| `tests/weights_files.rs` | 6 | The shipped weights load, misshapen networks are rejected, a Hybrid without a fitting network keeps its base tuning and says so, a base tuning out of range is read as the last one, Hybrid files saved with a score that isn't finite load again, a copy that doesn't load is skipped for the next one and networks that overflow don't crash (§8.7) |
| `tests/green_wave.rs` | 2 | The green wave runs every signal of a corridor fixed-time, and ending it gives back the controllers they ran before, except where another was chosen during the wave, without collisions; a single intersection isn't coordinated |
| `tests/networks.rs` | 7 | Backpropagation agrees with the gradient measured numerically, Adam fits a line, the shape check rejects every malformed network (sizes whose product overflows included), the target network moves part way toward the online one, the action mask is respected, Double DQN learns which action pays in which state and the replay memory keeps the latest 60,000 transitions |
| `tests/gui.rs` | 22 | The app, run without a window by `egui_kittest` and driven through its accessibility tree, the keyboard and the pointer: every panel opens and every control has a name; Space pauses and Step advances one second; every layout, control mode and controller runs, side by side too and along a corridor with the green wave; the demand, sensor and operations settings apply; the learning controllers show what they learn; every overlay and coloring draws; vehicles and pedestrians placed by hand, movements an approach lacks refused; a clicked vehicle's details; a vehicle of the cooperative crossing made to fail from the buttons and by a click, on both sides of a comparison; what *Stall one in the box* does on an empty crossing and once every lane with a vehicle on its way has a failure set; what a failed vehicle, one stopped behind it, one on its way out of the box and one whose crossing was withdrawn say when selected; pan, zoom and *Fit view*; both benchmark windows; *About* |
| `tests/scripted.rs` | 9 | Each `TS_*` variable of the scripted mode sets up its scene, a scripted screenshot stops the clock at its moment and screenshots are valid PNG files. The app reads the variables as it starts, so each scene opens in a process of its own |
| `tests/tools.rs` | 7 | `bench` compares every strategy on every layout without collisions, takes each arrival pattern and runs the sensor study; `train` trains, saves and resumes both learning controllers, in a scratch directory with its own home directory |
| `tests/tools.rs` | 10 | `bench` compares every strategy on every layout without collisions, takes each arrival pattern and runs the sensor study; `train` trains, saves and resumes both learning controllers, in a scratch directory with its own home directory, stops without touching the weights saved from the app when it can't make its `weights` folder, stops instead of reporting a result when it can't write the Hybrid's weights file, and stops with an error, making no folder, when no signalized layout has the name it is given |
| `src/bin/bench.rs` | 1 | A run for a strategy table counts a vehicle placed on top of another, so the `coll` column can show an overlap |
| `src/sim/coop.rs` | 4 | Approach profiles arrive on time and at speed, a short run-up enters slower but on time, the gap policies give the gaps in §6.11 and the following law holds its time gap |
| `src/sim/coop/failures.rs` | 6 | An emergency stop ends at rest after its braking distance, a trajectory holds the zones it rests in without end, a vehicle that can't stop behind another is expected at its rear and holds the zones it will stand in, a vehicle can be put anywhere along its route and passes clear of one at rest on another approach, a vehicle whose crossing was withdrawn brakes for its line while it doesn't yet respond to the vehicle ahead, and every gap allows the reaction time |
Expand Down Expand Up @@ -3428,7 +3433,9 @@ date:
against the version and runs `cargo publish` through crates.io's Trusted Publishing.
* **`scorecard.yml`** runs the OpenSSF Scorecard on every push to `main`, every Monday
and when branch protection changes.
* **Dependabot** proposes updates to the actions and the Cargo dependencies weekly.
* **Dependabot** proposes updates to the actions and to the dependencies named in
`Cargo.toml` weekly, and a security update for a version in `Cargo.lock` that GitHub
has an advisory for, when a fixed version exists.

| Platform | Packages | Built by | Signing |
|---|---|---|---|
Expand Down
Loading
Loading