urml-validator 0.1.0__tar.gz

urml_validator-0.1.0/.gitignore

@@ -0,0 +1,104 @@
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+.python-version
+
+# Test / coverage / mypy / pyright
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+.mypy_cache/
+.dmypy.json
+.pyre/
+.pyright/
+htmlcov/
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.tox/
+
+# --- Node / web tooling (kept out of core repo; here for safety) ---
+node_modules/
+.pnp.*
+.yarn/cache/
+.yarn/unplugged/
+.yarn/build-state.yml
+.yarn/install-state.gz
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# --- C++ / Rust build artifacts (in case reference runtimes land here in early Phase 1) ---
+target/
+*.o
+*.obj
+*.a
+*.lib
+*.dll
+*.dylib
+*.exe
+*.pdb
+cmake-build-*/
+CMakeCache.txt
+CMakeFiles/
+CMakeScripts/
+Testing/
+cmake_install.cmake
+install_manifest.txt
+compile_commands.json
+
+# --- ROS 2 build dirs ---
+build/
+install/
+log/
+
+# --- Editor and OS junk ---
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# --- Local-only artifacts ---
+.env
+.env.*
+*.log
+*.tmp
+.local/
+.scratch/
+
+# --- Outreach campaign artifacts (operational, not part of the open standard) ---
+# Target lists, message drafts, tracking data, and the launch-approval record
+# stay local. They are private to the maintainer; committing them would
+# telegraph the campaign before launch and could embarrass listed projects.
+outreach/

urml_validator-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: urml-validator
+Version: 0.1.0
+Summary: Static verification engine for URML — Universal Robot Language
+Project-URL: Homepage, https://github.com/URML-MARS/URML
+Project-URL: Repository, https://github.com/URML-MARS/URML
+Project-URL: Issues, https://github.com/URML-MARS/URML/issues
+Author: URML Maintainers
+License: Apache-2.0
+Keywords: robotics,specification,urml,validator
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
+</p>
+
+<p align="center">
+  A small, opinionated, human-readable language for describing robot intent.
+</p>
+
+<p align="center">
+  <a href="https://urml.dev"><b>urml.dev</b></a>
+</p>
+
+---
+
+# Validator
+
+**Status:** Phase 1 in flight. **Schemas + four-pass validator + `urml` CLI + JSON Schema export landed** at `0.1.0a1` (pre-alpha). Variable-binding type checking and the LLM bridge are the next milestones.
+
+## What this is
+
+The static verification engine for URML. Given a URML program, a Layer-1 capability manifest for the target robot, and the active safety envelope, the validator returns one of two outcomes:
+
+1. **Accepted** — the program is statically valid; the runtime may execute it.
+2. **Rejected with a structured error** — the program fails one or more checks; the error is a machine-readable object that a calling tool (often the LLM bridge) can use to revise the program.
+
+The validator is **the safety boundary**. Per [`MANIFESTO.md`](../../MANIFESTO.md) §Design Principles and [`CLAUDE.md`](../../CLAUDE.md) §What Claude Should Never Do:
+
+> *URML programs are executed only after static verification against the target's capability manifest and active safety envelope. Any "fast path" that skips verification is rejected on review.*
+
+Bypassing the validator is structurally hard because the validator and the runtimes are **separate processes**. A runtime that wanted to skip validation would have to be modified, not merely flagged.
+
+## What the validator checks
+
+When fully implemented, the validator runs these checks against every URML program:
+
+### Layer-3 (composition) checks
+
+- The program parses as valid URML against the layer-3 grammar.
+- Every composition operator is well-formed (no empty parallel, no retry with negative bound, no `on_error: substitute` referencing an undefined behavior).
+- Every `$variable` reference resolves to a prior `store_as`.
+- Types match across producer/consumer primitives.
+
+### Layer-2 (primitive) checks
+
+- Every primitive is in the spec (or in a profile the program declares).
+- Every primitive's required arguments are present and well-typed.
+- Profile-specific argument constraints are honored (e.g., drone-profile `move_to` declares altitude).
+
+### Layer-1 (capability) checks
+
+- The robot's manifest declares every capability the program needs (mobility, manipulation, perception, declared frames, declared locations).
+- Every named location in the program resolves in the manifest or the world model the manifest references.
+
+### Safety-envelope checks
+
+- Every declared limit is honored: max velocity, max payload, max force, max altitude, geofence, force ceilings, no-go zones, link-loss policy.
+- Profile-specific envelope checks (drone people-occupancy, industrial cell perimeter, home people-only zones) are applied for whichever profiles the program declares.
+
+## What the validator does NOT do
+
+- It does not execute the program. That is the runtime's job.
+- It does not parse natural language. That is the LLM bridge's job.
+- It does not generate the URML program. That is an LLM's job, via the LLM bridge.
+- It does not monitor runtime state. Run-time safety (an unexpected obstacle, a sudden wind gust, a person walking into the cell) is the substrate's job. The validator is **static**; the substrate is **dynamic**. Both are required for safety.
+
+## Language
+
+- **Python**, primary implementation. `mypy --strict`. Public API fully type-annotated.
+- A long-running validator service (e.g., as a sidecar to multiple runtimes in production) may eventually be backed by **Rust** for deployment ergonomics; the Python implementation remains the reference.
+
+## API (sketch)
+
+```python
+from urml.validator import validate, ValidationResult
+
+result: ValidationResult = validate(
+    program=program_yaml,         # str or parsed dict
+    manifest=manifest_yaml,        # str or parsed dict
+    envelope=envelope_yaml,        # str or parsed dict
+    profiles=("home",),            # which profiles the program declares
+    spec_versions={
+        "layer-1-hal": "0.1.0",
+        "layer-2-primitives": "0.1.0",
+        "layer-3-behavior": "0.1.0",
+    },
+)
+
+if result.accepted:
+    runtime.execute(result.program)
+else:
+    # result.errors is a list of structured errors,
+    # designed to be readable by an LLM and used for revision.
+    llm_bridge.revise(program_yaml, result.errors)
+```
+
+## Core Commitment
+
+The validator is part of the [Core Commitment](../../CORE_COMMITMENT.md). It will always be Apache 2.0. The safety guarantees of URML flow through this component; gating it behind a license would forfeit them.
+
+## Quickstart (current pre-alpha)
+
+```bash
+cd reference/validator
+python -m venv .venv && . .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+```
+
+The 22 tests confirm: the `red-mug` example parses against the schemas; every primitive accepts its minimal valid form; cross-field rules (e.g. `move_to` requires exactly one of `location`/`pose`, `capture(media: video)` requires `duration`, `release(mode: place)` requires `at`) fire correctly.
+
+What works **now** at this pre-alpha milestone:
+
+- Pydantic v2 schemas for Layer-1 (capability manifest), Layer-2 (all 12 RFC-0002 primitives), Layer-3 (composition), the safety envelope, and the top-level `URMLProgram`.
+- The Step / BehaviorOrStep tagged union accepts the YAML surface (`{move_to: {...}}`) and the recursive composition forms.
+- **The four-pass validator** — `urml_validator.validate(program, manifest, envelope, profiles)` runs argument, capability, envelope, and binding checks and returns a `ValidationResult` with structured `ValidationError`s. Error codes are stable and namespaced (`argument.*`, `capability.*`, `envelope.*`, `binding.*`); the LLM bridge will consume this format.
+- Example:
+
+  ```python
+  from urml_validator import validate
+
+  result = validate(program, manifest, envelope, profiles=("home",))
+  if result.accepted:
+      runtime.execute(program)
+  else:
+      for err in result.errors:
+          print(err.render())
+  ```
+
+### `urml` CLI
+
+After `pip install -e .` the `urml` console script is on PATH:
+
+```bash
+urml validate examples/home/red-mug.urml.yaml \
+  --manifest reference/validator/tests/fixtures/manifests/turtlebot4_home.yaml \
+  --envelope reference/validator/tests/fixtures/envelopes/home_default.yaml \
+  --profile home
+```
+
+Exit codes: **0** accepted, **1** validation failed, **2** usage error (missing file, bad YAML), **64** internal error.
+
+Add `--json` to emit the raw `ValidationResult` for machine consumers (LLM bridge revision flow, CI checks).
+
+### JSON Schema export
+
+```bash
+# Print one schema to stdout (suitable for piping into an LLM prompt fixture).
+urml schema --name program
+
+# Write all three schemas to a directory.
+urml schema --all --out-dir build/schemas/
+```
+
+Produces Draft 2020-12 schemas for `URMLProgram`, `CapabilityManifest`, and `SafetyEnvelope`. The LLM bridge consumes the program schema as the structured-output contract; robot makers consume the manifest schema when writing manifests by hand.
+
+The Python API mirrors the CLI:
+
+```python
+from urml_validator import export_schema, write_schemas
+
+schema = export_schema("program")  # dict
+write_schemas(Path("build/schemas/"))  # writes urml-{program,manifest,envelope}.schema.json
+```
+
+What's **not** in this milestone (lands next):
+
+- Variable-binding **type** checking across primitives (e.g., that `grasp(target: $foo)` requires `$foo` to be an Object-typed binding, not a Measurement).
+- Geometric geofence containment (polygon-vertex math).
+- The LLM bridge (`reference/llm-bridge/`).
+
+## Related documents
+
+- [`/spec/layer-1-hal/`](../../spec/layer-1-hal/) — manifest schema.
+- [`/spec/layer-2-primitives/`](../../spec/layer-2-primitives/) — primitive contracts.
+- [`/spec/layer-3-behavior/`](../../spec/layer-3-behavior/) — composition grammar.
+- [`/reference/llm-bridge/`](../llm-bridge/) — the primary consumer of structured validation errors.
+- [`/conformance/`](../../conformance/) — uses the validator as part of its end-to-end tests.

urml_validator-0.1.0/README.md

@@ -0,0 +1,177 @@
+<p align="center">
+  <a href="https://urml.dev"><img src="https://urml.dev/favicon.svg" alt="URML" width="72" height="72"></a>
+</p>
+
+<p align="center">
+  A small, opinionated, human-readable language for describing robot intent.
+</p>
+
+<p align="center">
+  <a href="https://urml.dev"><b>urml.dev</b></a>
+</p>
+
+---
+
+# Validator
+
+**Status:** Phase 1 in flight. **Schemas + four-pass validator + `urml` CLI + JSON Schema export landed** at `0.1.0a1` (pre-alpha). Variable-binding type checking and the LLM bridge are the next milestones.
+
+## What this is
+
+The static verification engine for URML. Given a URML program, a Layer-1 capability manifest for the target robot, and the active safety envelope, the validator returns one of two outcomes:
+
+1. **Accepted** — the program is statically valid; the runtime may execute it.
+2. **Rejected with a structured error** — the program fails one or more checks; the error is a machine-readable object that a calling tool (often the LLM bridge) can use to revise the program.
+
+The validator is **the safety boundary**. Per [`MANIFESTO.md`](../../MANIFESTO.md) §Design Principles and [`CLAUDE.md`](../../CLAUDE.md) §What Claude Should Never Do:
+
+> *URML programs are executed only after static verification against the target's capability manifest and active safety envelope. Any "fast path" that skips verification is rejected on review.*
+
+Bypassing the validator is structurally hard because the validator and the runtimes are **separate processes**. A runtime that wanted to skip validation would have to be modified, not merely flagged.
+
+## What the validator checks
+
+When fully implemented, the validator runs these checks against every URML program:
+
+### Layer-3 (composition) checks
+
+- The program parses as valid URML against the layer-3 grammar.
+- Every composition operator is well-formed (no empty parallel, no retry with negative bound, no `on_error: substitute` referencing an undefined behavior).
+- Every `$variable` reference resolves to a prior `store_as`.
+- Types match across producer/consumer primitives.
+
+### Layer-2 (primitive) checks
+
+- Every primitive is in the spec (or in a profile the program declares).
+- Every primitive's required arguments are present and well-typed.
+- Profile-specific argument constraints are honored (e.g., drone-profile `move_to` declares altitude).
+
+### Layer-1 (capability) checks
+
+- The robot's manifest declares every capability the program needs (mobility, manipulation, perception, declared frames, declared locations).
+- Every named location in the program resolves in the manifest or the world model the manifest references.
+
+### Safety-envelope checks
+
+- Every declared limit is honored: max velocity, max payload, max force, max altitude, geofence, force ceilings, no-go zones, link-loss policy.
+- Profile-specific envelope checks (drone people-occupancy, industrial cell perimeter, home people-only zones) are applied for whichever profiles the program declares.
+
+## What the validator does NOT do
+
+- It does not execute the program. That is the runtime's job.
+- It does not parse natural language. That is the LLM bridge's job.
+- It does not generate the URML program. That is an LLM's job, via the LLM bridge.
+- It does not monitor runtime state. Run-time safety (an unexpected obstacle, a sudden wind gust, a person walking into the cell) is the substrate's job. The validator is **static**; the substrate is **dynamic**. Both are required for safety.
+
+## Language
+
+- **Python**, primary implementation. `mypy --strict`. Public API fully type-annotated.
+- A long-running validator service (e.g., as a sidecar to multiple runtimes in production) may eventually be backed by **Rust** for deployment ergonomics; the Python implementation remains the reference.
+
+## API (sketch)
+
+```python
+from urml.validator import validate, ValidationResult
+
+result: ValidationResult = validate(
+    program=program_yaml,         # str or parsed dict
+    manifest=manifest_yaml,        # str or parsed dict
+    envelope=envelope_yaml,        # str or parsed dict
+    profiles=("home",),            # which profiles the program declares
+    spec_versions={
+        "layer-1-hal": "0.1.0",
+        "layer-2-primitives": "0.1.0",
+        "layer-3-behavior": "0.1.0",
+    },
+)
+
+if result.accepted:
+    runtime.execute(result.program)
+else:
+    # result.errors is a list of structured errors,
+    # designed to be readable by an LLM and used for revision.
+    llm_bridge.revise(program_yaml, result.errors)
+```
+
+## Core Commitment
+
+The validator is part of the [Core Commitment](../../CORE_COMMITMENT.md). It will always be Apache 2.0. The safety guarantees of URML flow through this component; gating it behind a license would forfeit them.
+
+## Quickstart (current pre-alpha)
+
+```bash
+cd reference/validator
+python -m venv .venv && . .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+```
+
+The 22 tests confirm: the `red-mug` example parses against the schemas; every primitive accepts its minimal valid form; cross-field rules (e.g. `move_to` requires exactly one of `location`/`pose`, `capture(media: video)` requires `duration`, `release(mode: place)` requires `at`) fire correctly.
+
+What works **now** at this pre-alpha milestone:
+
+- Pydantic v2 schemas for Layer-1 (capability manifest), Layer-2 (all 12 RFC-0002 primitives), Layer-3 (composition), the safety envelope, and the top-level `URMLProgram`.
+- The Step / BehaviorOrStep tagged union accepts the YAML surface (`{move_to: {...}}`) and the recursive composition forms.
+- **The four-pass validator** — `urml_validator.validate(program, manifest, envelope, profiles)` runs argument, capability, envelope, and binding checks and returns a `ValidationResult` with structured `ValidationError`s. Error codes are stable and namespaced (`argument.*`, `capability.*`, `envelope.*`, `binding.*`); the LLM bridge will consume this format.
+- Example:
+
+  ```python
+  from urml_validator import validate
+
+  result = validate(program, manifest, envelope, profiles=("home",))
+  if result.accepted:
+      runtime.execute(program)
+  else:
+      for err in result.errors:
+          print(err.render())
+  ```
+
+### `urml` CLI
+
+After `pip install -e .` the `urml` console script is on PATH:
+
+```bash
+urml validate examples/home/red-mug.urml.yaml \
+  --manifest reference/validator/tests/fixtures/manifests/turtlebot4_home.yaml \
+  --envelope reference/validator/tests/fixtures/envelopes/home_default.yaml \
+  --profile home
+```
+
+Exit codes: **0** accepted, **1** validation failed, **2** usage error (missing file, bad YAML), **64** internal error.
+
+Add `--json` to emit the raw `ValidationResult` for machine consumers (LLM bridge revision flow, CI checks).
+
+### JSON Schema export
+
+```bash
+# Print one schema to stdout (suitable for piping into an LLM prompt fixture).
+urml schema --name program
+
+# Write all three schemas to a directory.
+urml schema --all --out-dir build/schemas/
+```
+
+Produces Draft 2020-12 schemas for `URMLProgram`, `CapabilityManifest`, and `SafetyEnvelope`. The LLM bridge consumes the program schema as the structured-output contract; robot makers consume the manifest schema when writing manifests by hand.
+
+The Python API mirrors the CLI:
+
+```python
+from urml_validator import export_schema, write_schemas
+
+schema = export_schema("program")  # dict
+write_schemas(Path("build/schemas/"))  # writes urml-{program,manifest,envelope}.schema.json
+```
+
+What's **not** in this milestone (lands next):
+
+- Variable-binding **type** checking across primitives (e.g., that `grasp(target: $foo)` requires `$foo` to be an Object-typed binding, not a Measurement).
+- Geometric geofence containment (polygon-vertex math).
+- The LLM bridge (`reference/llm-bridge/`).
+
+## Related documents
+
+- [`/spec/layer-1-hal/`](../../spec/layer-1-hal/) — manifest schema.
+- [`/spec/layer-2-primitives/`](../../spec/layer-2-primitives/) — primitive contracts.
+- [`/spec/layer-3-behavior/`](../../spec/layer-3-behavior/) — composition grammar.
+- [`/reference/llm-bridge/`](../llm-bridge/) — the primary consumer of structured validation errors.
+- [`/conformance/`](../../conformance/) — uses the validator as part of its end-to-end tests.

urml_validator-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "urml-validator"
+version = "0.1.0"
+description = "Static verification engine for URML — Universal Robot Language"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+authors = [{ name = "URML Maintainers" }]
+keywords = ["robotics", "specification", "validator", "urml"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+  "pydantic>=2.6,<3",
+  "PyYAML>=6.0,<7",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-cov>=5",
+  "ruff>=0.5",
+  "mypy>=1.10",
+  "types-PyYAML>=6.0",
+]
+
+[project.scripts]
+urml = "urml_validator.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/URML-MARS/URML"
+Repository = "https://github.com/URML-MARS/URML"
+Issues = "https://github.com/URML-MARS/URML/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/urml_validator"]
+# Note: the policies/ directory inside src/urml_validator/ is included
+# automatically by the `packages` directive above. An earlier
+# `[tool.hatch.build.targets.wheel.force-include]` stanza added it a
+# second time, producing a duplicate-zip-entry that PyPI rejects on
+# upload (https://docs.pypi.org/archives). Do not re-add a
+# force-include for policies/.
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+  "E", "F", "W",      # pycodestyle + pyflakes
+  "I",                # isort
+  "B",                # flake8-bugbear
+  "UP",               # pyupgrade
+  "N",                # pep8-naming
+  "ANN",              # type annotations on public APIs
+  "RUF",
+]
+ignore = [
+  "ANN401",  # disallow Any — pydantic uses it legitimately
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["ANN"]   # tests don't need full type annotations
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+plugins = ["pydantic.mypy"]
+mypy_path = "src"
+packages = ["urml_validator"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = ["-q", "--strict-markers"]

urml_validator-0.1.0/src/urml_validator/__init__.py

@@ -0,0 +1,39 @@
+"""urml_validator — static verification engine for the Universal Robot Language.
+
+This package is the reference Python implementation of the URML validator.
+It owns the schema definitions for Layer-1 (capability manifest), Layer-2
+(intent primitives), and Layer-3 (behavior composition), plus the four-pass
+validator that checks a URML program against a manifest and a safety envelope
+before execution.
+
+The schemas are the source of truth; JSON Schema is exported on demand for
+non-Python consumers (the LLM bridge prompt contract, etc.).
+
+Stability: 0.1.0. The schemas track the RFC-0002 vocabulary; the
+five-pass validator and `urml` CLI are shipped, and the namespaced
+error codes in `errors.py` are a stable public API.
+"""
+
+from urml_validator._version import __version__
+from urml_validator.errors import ErrorCode, ValidationError, ValidationResult
+from urml_validator.policy_engine import evaluate_policy
+from urml_validator.schema_export import export_all_schemas, export_schema, write_schemas
+from urml_validator.schemas.policy import Policy, PolicyRule
+from urml_validator.schemas.program import URMLProgram
+from urml_validator.validator import DEFAULT_POLICY, validate
+
+__all__ = [
+    "DEFAULT_POLICY",
+    "ErrorCode",
+    "Policy",
+    "PolicyRule",
+    "URMLProgram",
+    "ValidationError",
+    "ValidationResult",
+    "__version__",
+    "evaluate_policy",
+    "export_all_schemas",
+    "export_schema",
+    "validate",
+    "write_schemas",
+]

urml_validator-0.1.0/src/urml_validator/_version.py

@@ -0,0 +1,9 @@
+"""Single source of truth for `__version__`.
+
+Kept in its own module so the package's submodules can import the version
+string without triggering circular imports through `__init__.py`.
+"""
+
+from __future__ import annotations
+
+__version__: str = "0.1.0"