physlint 0.1.0a1__tar.gz

physlint-0.1.0a1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/pranayjoshi/physlint/security/advisories/new
+    about: Report security issues privately rather than opening a public issue.
+  - name: Questions and adapter voting
+    url: https://github.com/pranayjoshi/physlint/discussions
+    about: Ask usage questions and help prioritize the next format adapter.

physlint-0.1.0a1/.github/ISSUE_TEMPLATE/false-positive.yml

@@ -0,0 +1,50 @@
+name: False positive
+description: Report a finding that does not represent a real dataset defect.
+title: "[false positive]: "
+labels: ["false-positive", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: Do not attach private datasets or reports containing sensitive paths. A minimal public reproduction is ideal.
+  - type: input
+    id: version
+    attributes:
+      label: Physlint version
+      placeholder: 0.1.0a1
+    validations:
+      required: true
+  - type: input
+    id: rule
+    attributes:
+      label: Rule ID
+      placeholder: video.frozen_frames
+    validations:
+      required: true
+  - type: input
+    id: format
+    attributes:
+      label: Dataset format and version
+      placeholder: LeRobot v3.0
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Why the finding is incorrect
+      description: Include declared FPS, relevant stream semantics, and a sanitized finding if possible.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+      description: Provide a public dataset revision or minimal fixture and the exact command/configuration.
+    validations:
+      required: true
+  - type: checkboxes
+    id: privacy
+    attributes:
+      label: Privacy confirmation
+      options:
+        - label: I removed credentials, private paths, images, and sensitive sample values.
+          required: true

physlint-0.1.0a1/.github/ISSUE_TEMPLATE/format-request.yml

@@ -0,0 +1,43 @@
+name: Format or adapter request
+description: Propose support for another physical-AI recording or dataset format.
+title: "[adapter]: "
+labels: ["adapter", "enhancement"]
+body:
+  - type: input
+    id: format
+    attributes:
+      label: Format and version
+      placeholder: MCAP with ROS 2 messages
+    validations:
+      required: true
+  - type: dropdown
+    id: data_kind
+    attributes:
+      label: Primary use
+      options:
+        - Recording/session validation
+        - Training-dataset validation
+        - Both
+    validations:
+      required: true
+  - type: textarea
+    id: semantics
+    attributes:
+      label: Stream and episode semantics
+      description: Explain how actions, observations, cameras, timestamps, and episode boundaries are represented.
+    validations:
+      required: true
+  - type: textarea
+    id: samples
+    attributes:
+      label: Public examples
+      description: Link immutable, redistributable examples and their expected healthy/defective behavior.
+    validations:
+      required: true
+  - type: textarea
+    id: rules
+    attributes:
+      label: Highest-value checks
+      description: Which defects have caused real collection or training failures?
+    validations:
+      required: true

physlint-0.1.0a1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What changed
+
+## Validation
+
+- [ ] `ruff check .`
+- [ ] `ruff format --check .`
+- [ ] `mypy`
+- [ ] `pytest`
+
+## Rule/adapter evidence
+
+- [ ] Positive and negative fixture added where applicable
+- [ ] Controlled corruption added where applicable
+- [ ] Capability, limitation, and `not_run` behavior documented
+- [ ] No network access, telemetry, source mutation, or sensitive report content introduced

physlint-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e '.[video,dev]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+      - run: pytest --cov=physlint --cov-report=term-missing

physlint-0.1.0a1/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,28 @@
+name: Publish to TestPyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/physlint/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

physlint-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Verify release tag matches package version
+        if: github.event_name == 'release'
+        run: |
+          PACKAGE_VERSION=$(python -c 'exec(open("src/physlint/_version.py").read()); print(__version__)')
+          test "v${PACKAGE_VERSION}" = "${GITHUB_REF_NAME}"
+      - run: python -m pip install --upgrade build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/physlint/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

physlint-0.1.0a1/.github/workflows/real-data-validation.yml

@@ -0,0 +1,31 @@
+name: Pinned real-data validation
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e '.[video,dev]' huggingface_hub
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface/hub
+          key: physlint-real-data-${{ hashFiles('validation/manifest.yaml') }}
+      - run: python -m validation.harness --output validation/reports/ci
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: sanitized-validation-reports
+          path: validation/reports/ci/
+          if-no-files-found: warn

physlint-0.1.0a1/.gitignore

@@ -0,0 +1,19 @@
+# Local product and implementation planning
+docs/plan/
+
+# Python/build artifacts
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+validation/.work/
+
+# Physlint output
+.physlint/

physlint-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0a1 — public alpha
+
+- Add 17 deterministic LeRobot v3 integrity rules and stable CI exit codes.
+- Make maximum-gap defaults scale with declared FPS while preserving absolute overrides.
+- Require aligned robot motion for frozen-camera findings.
+- Share one privacy-safe video analysis pass across video rules.
+- Group repeated gap and black-frame evidence.
+- Preserve Hugging Face repository identity and pinned source revision.
+- Separate NaN/Inf findings from null/empty stream-overlap semantics.
+- Add a reproducible four-dataset and three-corruption release gate.
+
+This alpha supports local LeRobot v3.x directories. MCAP/ROS 2 and Robomimic are roadmap items, not implemented adapters.

physlint-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+Use Python 3.11 or newer and install `.[video,dev]`. Before opening a change, run:
+
+```bash
+ruff check .
+ruff format --check .
+mypy
+pytest
+```
+
+Rules must include positive and negative fixtures, a controlled corruption test where applicable, stable evidence and remediation, documented limitations, and a characterized cost. Adapters must remain read-only, metadata-first, lazy over samples, and explicit about capabilities.
+
+New adapter proposals should start with the format-request issue template and include immutable public healthy examples, controlled defects, stream/episode semantics, and the real failure modes the adapter should catch. See `docs/roadmap.md` for the acceptance gate.
+
+The pinned public release gate is intentionally separate from normal CI because it downloads hundreds of MiB. Maintainers can run it locally with `python -m validation.harness` or trigger the manual real-data workflow.
+
+Do not add network access, telemetry, source-data mutation, large fixtures, or a new default dependency without an issue describing the measured requirement.

physlint-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Physlint contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

physlint-0.1.0a1/PKG-INFO

@@ -0,0 +1,350 @@
+Metadata-Version: 2.5
+Name: physlint
+Version: 0.1.0a1
+Summary: Local-first integrity validation for physical-AI and robot-learning data
+Project-URL: Homepage, https://github.com/pranayjoshi/physlint
+Project-URL: Documentation, https://github.com/pranayjoshi/physlint#readme
+Project-URL: Issues, https://github.com/pranayjoshi/physlint/issues
+Project-URL: Source, https://github.com/pranayjoshi/physlint
+Author: Pranay Joshi
+License: MIT
+License-File: LICENSE
+Keywords: data-quality,dataset-validation,lerobot,physical-ai,robotics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy<2.5,>=1.26
+Requires-Dist: pyarrow>=19.0.1
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6; extra == 'dev'
+Provides-Extra: video
+Requires-Dist: opencv-python-headless>=4.9; extra == 'video'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Physlint
+
+### Robot data integrity, before training.
+
+Local-first, deterministic validation for physical-AI recordings and robot-learning datasets.
+
+[![CI](https://img.shields.io/github/actions/workflow/status/pranayjoshi/physlint/ci.yml?branch=master&style=flat-square&label=CI)](https://github.com/pranayjoshi/physlint/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/pranayjoshi/physlint?include_prereleases&style=flat-square)](https://github.com/pranayjoshi/physlint/releases)
+![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)
+[![MIT](https://img.shields.io/badge/License-MIT-2ea44f?style=flat-square)](LICENSE)
+![Status](https://img.shields.io/badge/Status-Public%20Alpha-f59e0b?style=flat-square)
+
+[Quickstart](#quickstart) · [Demo](#see-it-catch-a-real-defect) · [Rules](#what-physlint-checks) · [Evidence](#reproducible-public-data-evidence) · [Roadmap](#format-roadmap) · [Contributing](#contributing)
+
+<img src="docs/assets/launch/exports/validation-summary.png" alt="Physlint public-alpha validation: four of four clean snapshots passed and three of three controlled corruptions were detected across 74 episodes and 31,258 frames." width="100%">
+
+</div>
+
+Physlint finds concrete integrity defects before robot data reaches training. It explains the impact, identifies the affected episode and stream, recommends remediation, writes a stable JSON report, and returns a CI-safe exit code.
+
+The `0.1.0a1` public alpha ships with a publicly validated **LeRobot Dataset v3.x** adapter. The engine is designed to grow into recording and dataset profiles for MCAP/ROS 2, Robomimic HDF5, RLDS/TFDS, and other physical-AI formats without pretending those adapters already exist.
+
+> [!IMPORTANT]
+> Physlint validates configured data-integrity contracts. A pass does not certify policy quality, task success, or robot safety.
+
+## Why Physlint?
+
+- **Catch failures before GPU time:** malformed manifests, broken episode ranges, reordered clocks, missing values, corrupt video, frozen cameras, and black frames become actionable findings.
+- **Keep robot data local:** `physlint check` performs no network requests and never modifies its source dataset.
+- **Get evidence, not a mystery score:** every finding includes a stable rule ID, severity, source location, observed condition, expected condition, impact, and remediation.
+- **Use it in CI:** deterministic execution, versioned JSON, atomic report writes, strict configuration, and documented exit codes.
+- **Trust scoped claims:** the public release gate pins exact dataset revisions and commits sanitized reports, corruption recipes, checksums, and publication metrics.
+
+## Quickstart
+
+Physlint requires Python 3.11 or newer.
+
+### Install from PyPI
+
+```bash
+python -m pip install "physlint[video]==0.1.0a1"
+```
+
+Until the package is published to PyPI, install this GitHub release directly:
+
+```bash
+python -m pip install "physlint[video] @ git+https://github.com/pranayjoshi/physlint.git@v0.1.0a1"
+```
+
+### Check a local LeRobot v3 dataset
+
+```bash
+physlint inspect /path/to/lerobot-dataset
+physlint check /path/to/lerobot-dataset
+```
+
+Write JSON to an exact destination:
+
+```bash
+physlint check /path/to/lerobot-dataset \
+  --output json \
+  --json-output artifacts/physlint-report.json
+```
+
+The source remains untouched. Exit code `0` means the configured contract passed; `1` means validation completed with a blocking finding.
+
+## See it catch a real defect
+
+These captures use the pinned Panda source from the release gate. The second dataset is a fully dereferenced copy with one deterministic NaN injected at episode 0, sample 5, state dimension 0.
+
+<table>
+  <tr>
+    <th width="50%">Clean pinned snapshot</th>
+    <th width="50%">Controlled NaN corruption</th>
+  </tr>
+  <tr>
+    <td><img src="docs/assets/launch/exports/clean-validation.png" alt="Physlint terminal output showing the clean pinned Panda LeRobot dataset passing 11 applicable rules with zero failures and zero errors."></td>
+    <td><img src="docs/assets/launch/exports/controlled-nan-failure.png" alt="Physlint terminal output showing a controlled NaN corruption failing numeric.finite_values with remediation guidance."></td>
+  </tr>
+</table>
+
+Physlint owns NaN and infinity semantics in `numeric.finite_values`; the same sample is not duplicated as a missing-stream finding.
+
+## What Physlint checks
+
+Seventeen deterministic rules are enabled by default:
+
+| Area | Checks |
+|---|---|
+| **Manifest** | Required files, declared/stored schema agreement, required streams, and feature shapes |
+| **Episodes** | Unique identifiers, positive lengths, non-overlapping boundaries, and stored-row agreement |
+| **Temporal** | Strictly monotonic timestamps, FPS cadence, FPS-aware maximum gaps, complete stream overlap, and observation/action delay when independently timestamped |
+| **Numeric** | NaN/Inf, configured physical bounds, and configured discontinuity limits |
+| **Video** | Complete decode, motion-aware frozen-frame runs, and grouped black/near-empty frames |
+
+List or explain the installed rule contract:
+
+```bash
+physlint rules
+physlint rules --json
+physlint explain temporal.max_gap
+physlint explain video.frozen_frames
+```
+
+Rules whose required inputs are unavailable return `not_run` with a reason; they are never misreported as passed. Robot-specific bounds and discontinuity checks stay `not_run` until the user supplies meaningful thresholds.
+
+Read the complete [MVP rule specifications](docs/rules/mvp-rules.md).
+
+## Configuration
+
+Run `physlint init` to generate a documented quality contract, or create `physlint.yaml` yourself:
+
+```yaml
+config_version: 1
+adapter: auto
+required_streams:
+  - observation.state
+  - action
+fail_on: error
+
+rules:
+  temporal.max_gap:
+    options:
+      # Default limit is 2× the interval implied by declared FPS.
+      max_gap_multiplier: 2.0
+
+  video.frozen_frames:
+    options:
+      max_consecutive_frames: 5
+      # Action is preferred over noisier observed state by default.
+      motion_streams: [action, observation.state]
+
+  numeric.configured_bounds:
+    options:
+      limits:
+        action:
+          min: [-1.0, -1.0]
+          max: [1.0, 1.0]
+
+  numeric.discontinuity:
+    options:
+      max_delta:
+        observation.state: [0.25, 0.25]
+
+reports:
+  json: true
+  output_dir: .physlint/reports
+```
+
+Use it explicitly when needed:
+
+```bash
+physlint check /path/to/dataset --config physlint.yaml
+```
+
+Unknown top-level keys, rule IDs, rule options, duplicate required streams, and invalid values are rejected instead of silently ignored.
+
+## CI integration
+
+The CLI has stable exit codes and writes reports atomically, so a basic GitHub Actions gate is small:
+
+```yaml
+- name: Install Physlint
+  run: python -m pip install "physlint[video]==0.1.0a1"
+
+- name: Validate robot dataset
+  run: |
+    physlint check "$DATASET_PATH" \
+      --json-output artifacts/physlint-report.json
+
+- uses: actions/upload-artifact@v4
+  if: always()
+  with:
+    name: physlint-report
+    path: artifacts/physlint-report.json
+```
+
+| Exit code | Meaning |
+|---:|---|
+| `0` | Validation completed and the configured contract passed |
+| `1` | Validation completed and the contract failed |
+| `2` | Invalid command or configuration |
+| `3` | Dataset or adapter failure |
+| `4` | Internal Physlint error |
+| `130` | Interrupted by the user |
+
+## Reproducible public-data evidence
+
+The alpha release gate evaluates four immutable public snapshots from four producers:
+
+| Dataset | Robot | Episodes | Frames | Applicable rules | Result |
+|---|---|---:|---:|---:|---|
+| [`ViaCatalyst/robomimic-can-ph-lerobot-v3`](https://huggingface.co/datasets/ViaCatalyst/robomimic-can-ph-lerobot-v3) | Panda | 10 | 1,160 | 11 | Pass |
+| [`cagataydev/scout-earth-rover-mini-20260616-053232`](https://huggingface.co/datasets/cagataydev/scout-earth-rover-mini-20260616-053232) | Earth Rover Mini | 3 | 4,176 | 14 | Pass |
+| [`lerobot/svla_so101_pickplace`](https://huggingface.co/datasets/lerobot/svla_so101_pickplace) | SO-101 | 50 | 11,939 | 14 | Pass |
+| [`vikram-avea/sentinel-demo-09`](https://huggingface.co/datasets/vikram-avea/sentinel-demo-09) | YAM humanoid | 11 | 13,983 | 14 | Pass |
+
+Clean-source result: **4/4 snapshots pass with zero findings and zero rule errors.** Controlled-defect recall: **3/3** for a non-finite value, reordered timestamps, and a deleted source row.
+
+Everything needed to audit or rerun those claims is versioned:
+
+- [Pinned repository manifest](validation/manifest.yaml)
+- [Deterministic corruption and execution harness](validation/harness.py)
+- [Sanitized reports and SHA-256 values](validation/reports/real-data-2026-08-24/summary.json)
+- [Publication-ready CSV](validation/reports/real-data-2026-08-24/summary.csv)
+- [Manual classification and performance analysis](docs/validation/real-data-2026-08-23.md)
+- [Reproduction instructions](validation/README.md)
+
+Runtime measurements are observations from the documented machine and run—not universal performance guarantees.
+
+## Format roadmap
+
+The storage format is an adapter boundary, not the product boundary.
+
+<img src="docs/assets/launch/exports/format-compatibility.png" alt="Physlint format compatibility table: LeRobot v3 implemented and validated; MCAP with ROS 2 profiles and Robomimic planned; RLDS, TFDS, ROS bag2, and ROS 1 bag under research." width="100%">
+
+| Format | Status | Intended mode |
+|---|---|---|
+| LeRobot Dataset v3.x | **Alpha—implemented and publicly validated** | Training datasets |
+| MCAP with ROS 2 profiles | Planned—seeking design partners | Recordings and derived datasets |
+| Robomimic HDF5 | Planned | Demonstration datasets |
+| RLDS/TFDS | Researching | Episode/step datasets |
+| ROS bag2 SQLite and ROS 1 bag | Researching | Recordings |
+
+MCAP needs two honest layers: container/channel health that works without training semantics, and an explicit profile mapping topics to actions, state, cameras, and episode boundaries. See the [cross-format roadmap](docs/roadmap.md) and [MCAP/ROS proposal](docs/design/mcap-ros.md).
+
+Use the adapter-request issue form to contribute an immutable public example and a real failure mode.
+
+## Current LeRobot boundary
+
+Supported:
+
+- LeRobot v3.x `meta/info.json` schema and path templates
+- Chunked Parquet episode metadata and sample shards
+- Multiple episodes per shared Parquet/MP4 file
+- Fixed-size and regular vector features
+- Shared video segments using per-camera timestamp ranges
+- Metadata-first discovery and bounded batch iteration
+
+Not currently supported:
+
+- LeRobot v2.0/v2.1
+- Remote Hub identifiers passed directly to `physlint check`
+- Image-directory features in the video rule set
+- Arbitrary codecs unavailable to the installed OpenCV build
+- Inferred safety, calibration, task-success, or coordinate-frame conclusions
+
+Read the [LeRobot adapter boundary](docs/adapters/lerobot.md).
+
+## Design principles
+
+```text
+source format → read-only adapter → canonical episodes/streams → capability planner
+                                                        ↓
+                                           deterministic rule engine
+                                                        ↓
+                                      terminal + versioned JSON evidence
+```
+
+- **Read only:** source datasets are never repaired or rewritten.
+- **Lazy by default:** metadata first, bounded Parquet batches, and one shared privacy-safe video analysis pass.
+- **Explicit applicability:** adapters advertise capabilities; unavailable checks explain why they did not run.
+- **Stable evidence:** rule versions, fingerprints, source revisions, and report schema are serialized.
+- **Exception isolation:** one rule failure cannot masquerade as a clean dataset pass.
+
+## Security and privacy
+
+Validation is offline. Reports contain source references, timestamps, aggregate statistics, and targeted evidence—not embedded images or complete source samples. Treat every dataset parser as an attack surface and report suspected vulnerabilities privately through [GitHub Security Advisories](https://github.com/pranayjoshi/physlint/security/advisories/new).
+
+See [SECURITY.md](SECURITY.md) before submitting a vulnerability. Do not attach private datasets or sensitive reports to public issues.
+
+## Contributing
+
+Contributions are welcome, particularly:
+
+- Public healthy and defective datasets for adapter release gates
+- False-positive reproductions
+- MCAP/ROS recording schemas and failure modes
+- New deterministic rules with controlled corruptions
+- Documentation, performance characterization, and privacy reviews
+
+Development setup:
+
+```bash
+git clone https://github.com/pranayjoshi/physlint.git
+cd physlint
+python -m pip install -e ".[video,dev]"
+
+ruff check .
+ruff format --check .
+mypy
+pytest
+```
+
+Rules require positive and negative fixtures, stable remediation, a bounded finding count, and controlled corruption evidence where applicable. Adapters must remain read-only, metadata-first, lazy over samples, and explicit about capabilities.
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md), open a format request, or join [GitHub Discussions](https://github.com/pranayjoshi/physlint/discussions).
+
+## Project status
+
+Physlint is an alpha. Its current claims are deliberately limited to the documented LeRobot v3 boundary and committed release evidence. The project does not train policies, repair data, host datasets, infer task success, produce an opaque quality score, or certify that a robot or policy is safe.
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+Physlint is available under the [MIT License](LICENSE).