Getting Started

Prerequisites

  • Python 3.14+
  • uv package manager
  • Git

Install

git clone https://github.com/eliask/lawvm.git
cd lawvm
uv sync

This installs the current public development checkout for evaluating the command surface.

Optional: archive-free structural evidence-pack demo

Choose this route for a small structural check; skip to Finnish replay if you already have the archive. The demo uses two public Maryland/Open Law repositories to audit declared structured publication operations and produce an evidence pack. Publisher authority and legal correctness remain outside that structural audit.

git clone https://github.com/maryland-dsd/law-xml.git .tmp/open_law/repos/law-xml
git clone https://github.com/maryland-dsd/law-xml-codified.git .tmp/open_law/repos/law-xml-codified

uv run lawvm open-law evidence-pack \
  --source-repo .tmp/open_law/repos/law-xml \
  --codified-repo .tmp/open_law/repos/law-xml-codified \
  --out .tmp/open_law/evidence-pack \
  --json

uv run lawvm open-law explain \
  --report-dir .tmp/open_law/evidence-pack \
  --limit 5

uv run lawvm open-law verify-pack \
  --report-dir .tmp/open_law/evidence-pack

The generated manifest records the local source states and remotes. See the repository’s Open Law demo notes for the claim boundary and follow-up queries.

Import source archives for Finnish replay

Finnish replay requires local archived sources. As of 11 August 2026 the two upstream ZIPs are roughly 17.2 GB combined; their sizes change, and ingestion needs additional local storage:

uv run lawvm import-zip \
  --statute-zip https://www.finlex.fi/api/assets/open-data/archives/statute.zip \
  --consolidated-zip https://www.finlex.fi/api/assets/open-data/archives/statute-consolidated.zip

This streams the official Finlex open-data archives into the content-addressed data/finlex.farchive database by default. Use --skip-existing to resume an interrupted import; subsequent Finnish commands read from the local archive.

First replay

Replay statute 2002/738 (Työturvallisuuslaki / Occupational Safety Act) as of January 1, 2024:

uv run lawvm replay 2002/738 --as-of 2024-01-01

This compiles the amendment acts available for 2002/738, replays admitted operations over the base statute, and materializes the point-in-time text for the selected profile. The result is a derived text-state with explicit residuals; it is not automatically a complete or authoritative statute.

First diff

Compare LawVM’s replay against the Finlex updated/derived comparison surface:

uv run lawvm diff 2002/738

This shows section-by-section divergences. Green sections match. Red sections diverge. Each divergence starts an investigation: replay defect, source gap, editorial convention, or candidate issue in the Finlex comparison surface.

First explain

See the amendment chain and operation history:

uv run lawvm explain 2002/738

This shows which amendments affected the statute, what operations they compiled to, and the temporal sequence of changes.

What success looks like

When replay succeeds on a statute with dozens of amendments spanning decades, you get:

  • Point-in-time text that may match the comparison surface for the declared corpus and profile
  • Provenance for the provisions and operations covered by the source account
  • Temporal versioning for dates and temporal rules represented by the declared source/profile

When replay diverges, typed residuals preserve the evidence needed to classify it as a replay defect, source pathology, editorial artifact, candidate comparison-surface issue, or unresolved case.

Run the benchmark

uv run lawvm bench --mode official_consolidation --corpus data/finland/bench_core.csv --no-save

Runs the included Finnish benchmark manifest without saving benchmark history or run artifacts. An August 2026 development run reported 0.23% mean normalized text edit distance. A newly acquired Finlex archive may produce a different result because publisher-controlled comparison surfaces change. See Artifacts for methodology and interpretation.

Explore further

uv run lawvm --help

The CLI includes replay, diff, explain, bench, bisect, and diagnose. Use --help for the exact command surface in your checkout.

Architecture documentation lives in notes/ in the repository. Start with notes/SPEC_INDEX.md.