sopvm 0.2.0__tar.gz

sopvm-0.2.0/.api-baseline.json

@@ -0,0 +1,22 @@
+{
+  "compile": [
+    "sop_path",
+    "policy_path"
+  ],
+  "check": [
+    "compiled"
+  ],
+  "Runtime": [
+    "compiled",
+    "providers"
+  ],
+  "__init__": [
+    "compiled",
+    "providers"
+  ],
+  "run": [],
+  "execute": [
+    "node",
+    "request_tool"
+  ]
+}

sopvm-0.2.0/.github/workflows/adversarial.yml

@@ -0,0 +1,31 @@
+name: Adversarial Security Tests
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  adversarial:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run adversarial test suite
+        run: |
+          pytest tests/adversarial/ -v --tb=short

sopvm-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade pip build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for PyPI trusted publishing (OIDC)
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses trusted publishing (OIDC) — no API token needed
+        # Configure at https://pypi.org/manage/project/sopvm/settings/publishing/

sopvm-0.2.0/.mimocode/.cron-lock

@@ -0,0 +1 @@
+{"pid":19240,"startedAt":1784354811742}

sopvm-0.2.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: sopvm-check
+  name: SOPVM policy check
+  description: Check a compiled SOP IR against a policy file
+  entry: sopvm check
+  language: python
+  types: [json]
+  args: ["--policy", "policy.yaml"]

sopvm-0.2.0/ARCHITECTURE.md

@@ -0,0 +1,81 @@
+# ARCHITECTURE.md
+
+SOPVM's architecture is built on one core principle: **the compiler never talks to a model, and the runtime never talks to raw SOP prose.** Everything the LLM sees at execution time came out of the compiler as a validated artifact.
+
+## Parser (`sopvm.parser`)
+
+**Milestone:** M2
+
+Parses strict YAML SOP files into a typed AST. Validates against a JSON Schema (`schemas/sop.schema.json`) and performs semantic checks (edge target resolution, reachability, capability grammar).
+
+**Design rationale:** YAML was chosen over Markdown (which M1 used) because it's unambiguous to parse and doesn't require a hand-written grammar. The JSON Schema provides machine-readable validation; the semantic checks catch logic errors that the schema can't express.
+
+**What the parser does NOT do:** It doesn't know about policies, capabilities, or execution semantics. It only validates structure.
+
+See [INTERFACES.md §1](INTERFACES.md#1-sop-source-format-owned-by-m2) for the exact YAML format.
+
+## AST (`sopvm.parser.ast`)
+
+**Milestone:** M2
+
+Frozen dataclasses representing the parsed SOP: `SopDocument`, `StepNode`, `CapabilityRequest`. Immutable — the AST is a build artifact, not a mutable state object.
+
+See [INTERFACES.md §2](INTERFACES.md#2-ast-owned-by-m2) for the exact shape.
+
+## Compiler (`sopvm.compiler`)
+
+**Milestones:** M3 (lowering), M5 (paging)
+
+Two passes:
+1. **Lower** (`lower.py`): Converts AST → IR (`CompiledProgram`). Direct 1:1 mapping, no optimization.
+2. **Page** (`page.py`): Computes `capabilities_paged` by intersecting declared capabilities against the policy via `satisfies()`. This is where the policy ceiling is applied.
+
+**Design rationale:** Separating lowering from paging makes each pass independently testable and keeps the IR clean. The IR is the *only* artifact the runtime reads — it never sees the AST or source YAML.
+
+**Why compilation is deterministic:** No LLM calls, no randomness, no side effects. Same input → same output, always. This is what makes the compiler testable without an API key.
+
+See [INTERFACES.md §4](INTERFACES.md#4-ir--program-graph-owned-by-m3-capability-annotated-by-m5) for the IR shape.
+
+## Capability Model (`sopvm.capability`, `sopvm.checker`)
+
+**Milestone:** M4
+
+Two layers:
+1. **Capability tokens** (`capability/token.py`): Parse `namespace:action(params)` strings into structured tokens. Comparator params (`<=`, `>=`) express ceilings in policy entries.
+2. **Static checker** (`checker/check.py`): Validates that every declared capability in the IR satisfies at least one policy entry. This is compile-time enforcement.
+
+**Design rationale:** Capabilities are unforgeable references, not strings the model can produce. The LLM never sees or manipulates a capability token directly — it only requests an action, and the gate decides whether the currently-held capability covers that action.
+
+See [INTERFACES.md §3](INTERFACES.md#3-capability-token-schema-owned-by-m4) for the token schema and policy format.
+
+## Runtime (`sopvm.runtime`)
+
+**Milestones:** M6 (executor), M7 (gate), M8 (providers)
+
+The runtime is a stack machine with an explicit program counter:
+1. **Executor** (`executor.py`): Drives the state machine. Fixed transition table, not ad hoc branching.
+2. **Capability gate** (`gate.py`): Intercepts every tool-call request. Checks against `capabilities_paged` for the current step. DENIED is a terminal fact — no retry, no recovery.
+3. **Provider registry + sandbox** (`plugins/`): Routes approved calls to registered providers. The sandbox catches providers lying about their own scope (defense in depth).
+
+**Design rationale:** The LLM is *never* trusted to control the program counter. It proposes ("I believe the precondition for branch B holds"), the engine decides. Every state transition is auditable via the telemetry system.
+
+**IR version check:** The executor rejects IR files with unsupported versions before execution begins, preventing confusing mid-execution failures.
+
+## Telemetry (`sopvm.telemetry`)
+
+**Milestone:** M10
+
+Every state transition and gate decision is emitted to a `TelemetrySink`. The `JsonlSink` produces append-only JSONL traces. Telemetry failures are silently degraded — a broken sink never crashes the run it's observing.
+
+See [INTERFACES.md §7](INTERFACES.md#7-event--telemetry-schema-owned-by-m10) for the event schema.
+
+## CLI (`sopvm.cli`)
+
+**Milestone:** M11
+
+Four subcommands: `compile`, `check`, `run`, `trace`. The `check` command is designed for pre-commit hooks (exit 1 on violations). No subcommand ever prints a raw Python traceback for expected failures.
+
+## Integration Points
+
+- **LangGraph** (`sopvm.integrations.langgraph`): Wraps a compiled SOP as a StateGraph node. This is the ONLY module allowed to import langgraph (enforced by AST-based import boundary test).
+- **Pre-commit** (`.pre-commit-hooks.yaml`): `sopvm-check` hook for CI/CD pipelines.

sopvm-0.2.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to SOPVM will be documented in this file.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-07-18
+
+> **Versioning note:** Per pre-1.0 SemVer convention, MINOR bumps (0.x)
+> may signal breaking changes. This release replaces the M1 public API
+> (`compile_check()`, Markdown input, argparse CLI) with the M2-M13
+> public API (`compile()`, `check()`, `Runtime`, YAML input, click CLI).
+> See VERSIONING_POLICY.md for details.
+
+### Added
+- **M2**: SOP YAML parser with JSON Schema validation and semantic checks
+- **M3**: AST→IR lowering pass (`CompiledProgram`, `IrNode`)
+- **M4**: Capability token parser, policy loader, static checker (`satisfies()`, `check()`)
+- **M5**: Paging pass (`apply_paging()`) and compile pipeline (`compile_sop()`)
+- **M6**: Runtime executor with state machine, event hooks, infinite-loop detection
+- **M7**: Capability gate — runtime tool-call interception and enforcement
+- **M8**: Plugin architecture — `ToolProvider`, `ProviderRegistry`, sandbox wrapper
+- **M9**: LangGraph integration adapter (`as_langgraph_node()`)
+- **M10**: Telemetry — `Event`, `EventType` enum, `TelemetrySink`, `JsonlSink`
+- **M11**: CLI with `compile`, `check`, `run`, `trace` subcommands (click)
+- **M12**: Adversarial security test suite (25+ test cases, CI-gated)
+- **M13**: Public API stabilization — `sopvm.compile()`, `sopvm.check()`, `sopvm.Runtime`
+- Pre-commit hook (`sopvm-check`)
+- IR version validation — `UnsupportedIrVersionError` for unsupported IR files
+- API compatibility CI check script
+- JSON Schema for SOP YAML format (`schemas/sop.schema.json`)
+- JSON Schema for capability tokens (`schemas/capability.schema.json`)
+
+### Security
+- **M4**: Static capability checker catches policy ceiling violations at compile time
+- **M7**: Runtime capability gate denies out-of-scope tool calls
+- **M8**: Provider sandbox catches lying providers (defense in depth)
+- **M12**: IR tampering detection — runtime re-validates `capabilities_paged` against policy
+- **M12**: Adversarial test corpus covers 25+ escalation techniques
+
+### Changed
+- **M5**: Replaced M3's placeholder `capabilities_paged = capabilities_declared` with real policy-resolved subset
+- **M10**: Extended M6's stub `Event` with full telemetry schema (EventType enum, timestamps, run_id)
+
+### Fixed
+- **M12**: Fixed IR tampering gap — executor now re-validates capabilities_paged at run time when policy is provided
+
+## [0.1.0] - 2026-07-18
+
+### Added
+- Initial release: Markdown+frontmatter SOP parser (M1)
+- `sopvm compile --check` CLI command
+- Unit tests for parser

sopvm-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to SOPVM
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/your-org/sopvm.git
+cd sopvm
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run the full test suite
+make ci
+# or equivalently:
+pytest tests/ -v
+```
+
+## Project Structure
+
+```
+src/sopvm/
+├── parser/          # M2: YAML parser + AST
+├── ir/              # M3: IR data model
+├── compiler/        # M3+M5: lowering + paging
+├── capability/      # M4: token parser + policy loader
+├── checker/         # M4: static capability checker
+├── runtime/         # M6-M8: executor, gate, violations
+├── plugins/         # M8: tool providers + registry + sandbox
+├── integrations/    # M9: LangGraph adapter (ONLY place langgraph is imported)
+├── telemetry/       # M10: events + sinks
+├── cli/             # M11: click CLI
+tests/
+├── unit/            # Compiler + capability + scheduler unit tests
+├── integration/     # Runtime + pipeline integration tests
+├── adversarial/     # M12: security test corpus (CI-gated)
+├── golden/          # AST/IR JSON snapshot tests
+├── property/        # Hypothesis property-based tests
+```
+
+## Running Tests
+
+```bash
+# Full suite
+pytest tests/ -v
+
+# Just adversarial tests (CI-gated)
+pytest tests/adversarial/ -v
+
+# With coverage
+pytest tests/ --cov=src/sopvm --cov-report=term-missing
+
+# Property-based tests only
+pytest tests/property/ -v
+```
+
+## Test Taxonomy
+
+| Category | Purpose | When to add |
+|---|---|---|
+| `unit/` | Isolated component tests | Any new function/class |
+| `integration/` | End-to-end pipeline tests | New milestone or cross-component feature |
+| `adversarial/` | Security boundary tests | New escalation technique or enforcement layer |
+| `golden/` | Snapshot regression tests | Any change to AST/IR output format |
+| `property/` | Hypothesis fuzz tests | Any invariant that holds for all valid inputs |
+
+## Proposing INTERFACES.md Changes
+
+INTERFACES.md is the single source of truth for cross-milestone schemas. Changes require:
+
+1. **Read the Change Control section** at the bottom of INTERFACES.md
+2. **Version bump** to the affected schema
+3. **Explicit call-out** in the milestone prompt listing which section changed and why
+4. **Update all consuming modules** — a schema change in §2 (AST) must propagate to §3 (capability), §4 (IR), etc.
+
+Do NOT silently redefine a schema. If you need a new field, add it (MINOR bump). If you need to remove or rename a field, that's a breaking change (MAJOR bump).
+
+## Code Style
+
+- Python 3.10+ only
+- No comments unless the WHY is non-obvious
+- Frozen dataclasses for all data structures
+- No runtime state mutations in the compiler/checker path

sopvm-0.2.0/INTERFACES.md

@@ -0,0 +1,231 @@
+# SOPVM — INTERFACES.md (canonical contract doc)
+
+Status: DRAFT skeleton. Every later milestone prompt must conform to this or explicitly call out a proposed change here first. This file is the single source of truth for cross-milestone shapes — no milestone may silently redefine a schema it doesn't own.
+
+Ownership: each section names the milestone that *defines* it. Other milestones may *consume* it but not *redefine* it.
+
+---
+
+## 1. SOP Source Format (owned by M2)
+
+Strict YAML, validated against a JSON Schema (`schemas/sop.schema.json`). No free-form prose fields feed the compiler — only structured fields do.
+
+```yaml
+sop_version: "0.1"
+name: "refund-request-handling"
+policy: "policies/support-agent.policy.yaml"   # top-level capability ceiling (see §3)
+
+steps:
+  - id: verify_identity
+    description: "Confirm requester identity via order lookup"
+    requires:
+      capabilities: ["db:read(orders)"]
+    on_success: check_eligibility
+    on_failure: escalate_human
+
+  - id: check_eligibility
+    description: "Check refund policy eligibility"
+    requires:
+      capabilities: ["db:read(orders)", "db:read(policy_rules)"]
+    on_success: issue_refund
+    on_failure: escalate_human
+
+  - id: issue_refund
+    description: "Issue refund via payment provider"
+    requires:
+      capabilities: ["payments:refund(max_amount=100.00)"]
+    on_success: notify_user
+    on_failure: escalate_human
+
+  - id: notify_user
+    terminal: true
+    requires:
+      capabilities: ["notify:email"]
+
+  - id: escalate_human
+    terminal: true
+    requires:
+      capabilities: ["notify:slack(channel=support-escalations)"]
+```
+
+Rules M2 must enforce at parse time:
+- every `on_success`/`on_failure` target must resolve to a declared step id
+- every non-terminal step must declare at least one outgoing edge
+- `capabilities` entries must match the capability grammar in §3
+- unreferenced steps (unreachable from the declared entry point) are a parse error, not a warning
+
+---
+
+## 2. AST (owned by M2)
+
+Internal only — not a public contract, but shape is fixed here so M3 doesn't guess:
+
+```
+SopDocument
+├── version: str
+├── policy_ref: str
+└── steps: list[StepNode]
+     StepNode
+     ├── id: str
+     ├── description: str
+     ├── requires: CapabilityRequest[]
+     ├── edges: {on_success: str|None, on_failure: str|None}
+     └── terminal: bool
+```
+
+---
+
+## 3. Capability Token Schema (owned by M4)
+
+Auditable outside Python — `schemas/capability.schema.json`.
+
+Grammar: `namespace:action(param=value, ...)` — parameterized, not a flat string enum (see MILESTONES.md risk #2).
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CapabilityToken",
+  "type": "object",
+  "required": ["namespace", "action", "params"],
+  "properties": {
+    "namespace": { "type": "string", "examples": ["fs", "net", "db", "payments", "notify"] },
+    "action":    { "type": "string", "examples": ["read", "write", "http", "refund"] },
+    "params":    { "type": "object", "additionalProperties": true },
+    "raw":       { "type": "string", "description": "original string form, e.g. payments:refund(max_amount=100.00)" }
+  }
+}
+```
+
+Policy file (top-level ceiling a SOP may never exceed):
+
+```yaml
+# policies/support-agent.policy.yaml
+policy_version: "0.1"
+allowed_capabilities:
+  - "db:read(orders)"
+  - "db:read(policy_rules)"
+  - "payments:refund(max_amount<=100.00)"
+  - "notify:email"
+  - "notify:slack(channel=support-escalations)"
+```
+
+Static checker (M4) contract: given a compiled IR + a policy file, return a `CheckResult`:
+
+```json
+{
+  "passed": false,
+  "violations": [
+    {
+      "step_id": "issue_refund",
+      "requested": "payments:refund(max_amount=250.00)",
+      "reason": "exceeds policy ceiling payments:refund(max_amount<=100.00)"
+    }
+  ]
+}
+```
+
+This must be checkable **without running the runtime** — pure static analysis, usable as a pre-commit hook (M11).
+
+---
+
+## 4. IR / Program Graph (owned by M3, capability-annotated by M5)
+
+```json
+{
+  "ir_version": "0.1",
+  "entry": "verify_identity",
+  "nodes": {
+    "verify_identity": {
+      "capabilities_declared": ["db:read(orders)"],
+      "capabilities_paged": ["db:read(orders)"],
+      "edges": { "on_success": "check_eligibility", "on_failure": "escalate_human" },
+      "terminal": false
+    }
+  }
+}
+```
+
+- `capabilities_declared`: what the source SOP asked for at this step (from AST, unchanged by compiler).
+- `capabilities_paged`: what M5's paging-plan pass actually resolves as grantable *at this step* (may be a subset after policy intersection — never a superset of `capabilities_declared`).
+- IR is the only artifact the runtime (M6) ever reads. The runtime never sees the AST or source YAML directly.
+
+---
+
+## 5. Runtime State Machine (owned by M6)
+
+States per step: `PENDING → RUNNING → {DONE, FAILED, DENIED}`.
+
+- `DENIED` is a distinct terminal state from `FAILED` — a capability violation is not an execution error, it's a policy event, and M10's telemetry must be able to tell them apart.
+- Transition rules are a fixed table, not branching logic scattered through the executor — this table is what M12's adversarial tests assert against.
+
+---
+
+## 6. Tool Provider / Plugin Interface (owned by M8)
+
+```python
+class ToolProvider(Protocol):
+    def declared_capabilities(self) -> list[str]: ...
+    def invoke(self, capability: CapabilityToken, args: dict) -> ToolResult: ...
+```
+
+- `invoke` is never called directly by step logic — only by the gate (M7), which checks `capability` against `capabilities_paged` for the current step first.
+- A provider that lies about `declared_capabilities()` (requests more at invoke time than it declared) is itself a `DENIED` event, not a crash.
+
+---
+
+## 7. Event / Telemetry Schema (owned by M10)
+
+```json
+{
+  "event": "capability_denied",
+  "step_id": "issue_refund",
+  "requested": "payments:refund(max_amount=250.00)",
+  "paged": ["payments:refund(max_amount<=100.00)"],
+  "timestamp": "2026-07-18T12:00:00Z",
+  "run_id": "..."
+}
+```
+
+Event types (fixed enum, extend via versioning policy only): `step_started`, `step_completed`, `step_failed`, `capability_granted`, `capability_denied`, `run_started`, `run_completed`.
+
+---
+
+## 8. Public API (owned by M13, staged incrementally by M3/M6/M11)
+
+```python
+sopvm.compile(sop_path: str, policy_path: str) -> CompiledProgram
+sopvm.check(compiled: CompiledProgram) -> CheckResult
+sopvm.Runtime(compiled: CompiledProgram, providers: list[ToolProvider])
+    .run() -> RunResult
+```
+
+Anything not in this list is internal and may change without a version bump.
+
+---
+
+## 9. CLI Contract (owned by M11)
+
+```
+sopvm compile <sop.yaml> --policy <policy.yaml> -o <out.ir.json>
+sopvm check <out.ir.json> --policy <policy.yaml>        # exit 1 on violation, for pre-commit
+sopvm run <out.ir.json> --providers <providers.yaml>
+sopvm trace <run_id>                                     # replay telemetry
+```
+
+---
+
+## 10. LangGraph Adapter (owned by M9)
+
+Adapter module only — must not leak LangGraph types into M1–M8. Exposes SOPVM as a single callable node:
+
+```python
+def as_langgraph_node(compiled: CompiledProgram, providers: list[ToolProvider]) -> Callable
+```
+
+---
+
+## Change control
+
+Any edit to a section above after its owning milestone has merged requires:
+1. A version bump to the affected schema (see VERSIONING_POLICY.md)
+2. An explicit call-out in the milestone prompt that changes it, listing exactly which section of this file is being modified and why

sopvm-0.2.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: sopvm
+Version: 0.2.0
+Summary: A compiler and capability-gated runtime for Standard Operating Procedures executed by LLM agents.
+Author: Sushit
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hypothesis>=6.90; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# SOPVM
+
+**A runtime layer beneath agent frameworks — not another one.**
+
+SOPVM compiles Standard Operating Procedures into executable programs and runs them on a capability-gated stack machine. It sits *underneath* LangGraph, CrewAI, or any tool-calling loop — the same way LLVM sits underneath Clang, Rust, and Swift rather than competing with any single language.
+
+## Why Compilation Matters
+
+Most "follow the SOP" approaches today mean "paste the SOP text into a system prompt and hope." The LLM re-plans every step, inconsistently. SOPVM compiles the SOP once into a deterministic, auditable program. The LLM only does the semantic work (interpreting what a step means); the runtime handles state tracking, capability enforcement, and execution flow. This is measurably better — the research paper behind SOPVM shows up to 16-point accuracy gains over raw prose.
+
+## Quickstart
+
+```bash
+# Install
+pip install -e ".[dev]"
+
+# Compile a SOP against a policy
+sopvm compile examples/sops/refund-request-handling.sop.yaml \
+    --policy policies/support-agent.policy.yaml \
+    -o compiled.ir.json
+
+# Check for policy violations (pre-commit mode)
+sopvm check compiled.ir.json --policy policies/support-agent.policy.yaml
+# exit 0 = all capabilities within policy
+# exit 1 = violations found
+
+# Execute the compiled SOP
+sopvm run compiled.ir.json
+```
+
+### Example: compile and check
+
+```
+$ sopvm compile tests/fixtures/refund-request-handling.sop.yaml \
+    --policy policies/support-agent.policy.yaml \
+    -o compiled.ir.json
+Compiled to compiled.ir.json
+
+$ sopvm check compiled.ir.json --policy policies/support-agent.policy.yaml
+All capabilities within policy.
+```
+
+### Example: policy violation caught at check time
+
+```
+$ sopvm check violating.ir.json --policy policies/support-agent.policy.yaml
+VIOLATION step=a requested='payments:refund(max_amount=250.00)' reason=exceeds policy ceiling payments:refund(max_amount<=100.00)
+```
+
+### Example: runtime execution
+
+```
+$ sopvm run compiled.ir.json
+Final state: DONE
+Path: verify_identity -> check_eligibility -> issue_refund -> notify_user
+```
+
+## Architecture
+
+```
+SOP YAML ──► Parser ──► AST ──► Compiler ──► IR ──► Runtime ──► Result
+             (M2)       (M2)   (M3+M5)     (M3)  (M6-M8)
+                                          ┌──────┴──────┐
+                                          │ Gate │Plugins│
+                                          │ (M7) │ (M8)  │
+                                          └──────┴──────┘
+```
+
+| Box | Module | Milestone |
+|---|---|---|
+| Parser | `sopvm.parser` | M2 |
+| AST | `sopvm.parser.ast` | M2 |
+| Compiler (lower+page) | `sopvm.compiler` | M3, M5 |
+| IR | `sopvm.ir` | M3 |
+| Runtime (gate+providers) | `sopvm.runtime` | M6-M8 |
+| Static Checker | `sopvm.checker` | M4 |
+| Telemetry | `sopvm.telemetry` | M10 |
+| CLI | `sopvm.cli` | M11 |
+| LangGraph Adapter | `sopvm.integrations.langgraph` | M9 |
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed design rationale.
+
+## Documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — component design and rationale
+- [INTERFACES.md](INTERFACES.md) — canonical contract schemas (M2-M13)
+- [VERSIONING_POLICY.md](VERSIONING_POLICY.md) — SemVer rules
+- [CHANGELOG.md](CHANGELOG.md) — release history
+- [CONTRIBUTING.md](CONTRIBUTING.md) — development setup
+
+## Examples
+
+- `examples/sops/` — example SOP YAML files
+- `examples/providers/` — reference tool provider implementations
+- `examples/langgraph_integration.py` — LangGraph StateGraph wrapper
+- `examples/adversarial_walkthrough.md` — step-by-step escalation attempt