worldstate-check 0.1.1__tar.gz

worldstate_check-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sylvester Kaczmarek
+
+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.

worldstate_check-0.1.1/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: worldstate-check
+Version: 0.1.1
+Summary: Deterministic postcondition verification for AI agents and autonomous systems.
+Author: Sylvester Kaczmarek
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sylvesterkaczmarek/worldstate-check
+Project-URL: Repository, https://github.com/sylvesterkaczmarek/worldstate-check
+Project-URL: Issues, https://github.com/sylvesterkaczmarek/worldstate-check/issues
+Keywords: ai-agents,autonomy,verification,assurance,robotics,telemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6.0.2
+Dynamic: license-file
+
+# WorldState Check
+
+![WorldState Check](assets/social/github-social-card-worldstate-check.png)
+
+[![CI](https://github.com/sylvesterkaczmarek/worldstate-check/actions/workflows/ci.yml/badge.svg)](https://github.com/sylvesterkaczmarek/worldstate-check/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+**Verify that an autonomous action changed the world as intended.**
+
+WorldState Check evaluates explicit postconditions against independent observations after an AI agent, automation, robot, or autonomous system acts. It distinguishes a successful command from a verified outcome, uses deterministic verdict logic, and produces a structured evidence report without requiring an LLM judge.
+
+## At a glance
+
+```text
+INTENT
+  |
+ACTION
+  |
+ACKNOWLEDGEMENT
+  |
+OBSERVED WORLD STATE
+  |
+POSTCONDITIONS
+  |
+VERIFIED / NOT_VERIFIED / UNCERTAIN
+```
+
+A tool call returning success is not the same as the requested state being achieved.
+
+```text
+Agent: "Safe mode entered."
+
+$ worldstate-check demo
+
+[PASS   ] command-ack
+[PASS   ] payload-power
+[FAIL   ] attitude-error
+[PASS   ] battery-soc
+
+VERDICT: NOT_VERIFIED
+Required checks: 3/4 passed
+```
+
+The command was acknowledged and the payload was powered down, but the synthetic attitude error remained outside the required bound.
+
+## Why this is useful
+
+The same verification pattern applies across software and physical autonomy:
+
+- an agent says a deployment succeeded, but the health endpoint still fails;
+- a maintenance workflow closes a job, but the measured equipment state remains outside limits;
+- a spacecraft accepts a safe-mode command, but telemetry shows the required attitude was not reached;
+- an automation reports completion, but the expected file, process, API state, or database-facing evidence is absent.
+
+WorldState Check makes the success condition explicit and evaluates observable state instead of trusting the actor's completion claim.
+
+## Check types
+
+| Type | What it verifies |
+| --- | --- |
+| `file` | existence, text assertions, SHA-256 |
+| `json` | structured state through deterministic field comparisons |
+| `metric` | JSON or CSV telemetry, thresholds, ranges, freshness |
+| `http` | status, response text, JSON response state; network access is opt-in |
+| `tcp` | endpoint reachability; network access is opt-in |
+| `command` | explicit verification commands, opt-in only |
+
+Required checks produce one of three verdicts:
+
+- `VERIFIED` when every required postcondition passes;
+- `NOT_VERIFIED` when at least one required postcondition fails;
+- `UNCERTAIN` when no required check fails but reliable evidence is unavailable for one or more required checks.
+
+## Quick start
+
+```bash
+git clone https://github.com/sylvesterkaczmarek/worldstate-check.git
+cd worldstate-check
+python -m pip install .
+worldstate-check demo
+```
+
+Run a passing synthetic scenario:
+
+```bash
+worldstate-check demo --scenario verified
+```
+
+Create a starter specification:
+
+```bash
+worldstate-check init worldstate.yaml
+```
+
+Validate it without touching any evidence source:
+
+```bash
+worldstate-check validate worldstate.yaml
+```
+
+Then verify the observed state:
+
+```bash
+worldstate-check verify worldstate.yaml
+```
+
+Specifications that intentionally contact HTTP or TCP endpoints must opt in:
+
+```bash
+worldstate-check verify deployment.yaml --allow-network
+```
+
+Write a machine-readable evidence report:
+
+```bash
+worldstate-check verify worldstate.yaml --report evidence.json
+worldstate-check verify-report evidence.json
+```
+
+## Verification specification
+
+```yaml
+version: 1
+task: spacecraft-safe-mode
+
+checks:
+  - id: payload-off
+    type: json
+    path: telemetry.json
+    field: payload.power
+    operator: eq
+    value: "off"
+
+  - id: attitude-error
+    type: metric
+    source:
+      type: json
+      path: telemetry.json
+      field: attitude.error_deg
+    operator: lte
+    value: 3.0
+
+  - id: battery-reserve
+    type: metric
+    source:
+      type: json
+      path: telemetry.json
+      field: battery.soc
+    operator: gte
+    value: 25.0
+```
+
+See [docs/specification.md](docs/specification.md) for all supported checks.
+
+## Telemetry freshness
+
+A value can be numerically valid and still be unsafe evidence if it is stale. Metric checks can require a recent timestamp:
+
+```yaml
+- id: temperature
+  type: metric
+  source:
+    type: json
+    path: telemetry.json
+    field: temperature_c
+    timestamp_field: observed_at
+    max_age_seconds: 5
+  operator: lte
+  value: 75
+```
+
+Stale required telemetry causes `NOT_VERIFIED` because the available observation does not satisfy the declared freshness postcondition.
+
+## Waiting for eventual state
+
+Some effects are asynchronous. `--wait` re-evaluates the postconditions until they pass or the timeout expires:
+
+```bash
+worldstate-check verify deployment.yaml --wait 30
+```
+
+The report records the number of attempts. Keep verification checks idempotent when using retries.
+
+## Safety boundaries
+
+WorldState Check treats the verification specification as potentially powerful input.
+
+- evidence paths are confined to the verification root by default;
+- paths outside that root require `--allow-outside-root`;
+- command checks require `--allow-command`;
+- HTTP and TCP checks require `--allow-network`;
+- commands use an argument vector with `shell=False`;
+- command checks receive only a minimal environment and do not copy raw argv or output into evidence reports;
+- HTTP evidence redacts URL credentials, query strings, and fragments;
+- specifications and evidence reads have explicit size limits.
+
+See [docs/security.md](docs/security.md).
+
+## Example physical-system checks
+
+The repository contains two runnable file-backed examples:
+
+```bash
+worldstate-check verify examples/field-maintenance.yaml
+worldstate-check verify examples/spacecraft-safe-mode.yaml
+```
+
+The first is expected to verify. The second is intentionally expected to return `NOT_VERIFIED` because the attitude-error postcondition fails.
+
+## Evidence report
+
+JSON reports include:
+
+- task and final verdict;
+- every expected and observed value;
+- required versus optional checks;
+- timing and attempt count;
+- source metadata such as evidence path, endpoint, or telemetry age;
+- a SHA-256 digest of the report payload.
+
+`worldstate-check verify-report` recomputes that digest and reports whether the saved payload still matches it. The digest is not a digital signature and does not establish the identity or trustworthiness of the evidence source.
+
+## Assurance model
+
+WorldState Check verifies declared postconditions against observations. It does not prove that sensors, endpoints, files, or other evidence sources are trustworthy or correctly calibrated. It also does not determine whether the original intent was safe.
+
+See [docs/assurance-model.md](docs/assurance-model.md) for the exact scope.
+
+## Repository layout
+
+```text
+worldstate-check/
+├── .github/workflows/ci.yml
+├── assets/social/
+├── docs/
+├── examples/
+├── src/worldstate_check/
+│   ├── checks/
+│   ├── cli.py
+│   ├── engine.py
+│   ├── loader.py
+│   ├── models.py
+│   └── report.py
+├── tests/
+├── CITATION.cff
+├── LICENSE
+├── Makefile
+├── pyproject.toml
+└── README.md
+```
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m pip install pytest
+pytest
+```
+
+The core verdict path is deterministic and does not call an LLM.
+
+## Cite this repository
+
+If you use or adapt this repository, please cite:
+
+> Kaczmarek, S. (2026). *WorldState Check*. GitHub. https://github.com/sylvesterkaczmarek/worldstate-check
+
+```bibtex
+@software{Kaczmarek_2026_WorldState_Check,
+  author = {Sylvester Kaczmarek},
+  title  = {{WorldState Check}},
+  year   = {2026},
+  url    = {https://github.com/sylvesterkaczmarek/worldstate-check}
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+© **Sylvester Kaczmarek** · [https://www.sylvesterkaczmarek.com](https://www.sylvesterkaczmarek.com)

worldstate_check-0.1.1/README.md

@@ -0,0 +1,282 @@
+# WorldState Check
+
+![WorldState Check](assets/social/github-social-card-worldstate-check.png)
+
+[![CI](https://github.com/sylvesterkaczmarek/worldstate-check/actions/workflows/ci.yml/badge.svg)](https://github.com/sylvesterkaczmarek/worldstate-check/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+**Verify that an autonomous action changed the world as intended.**
+
+WorldState Check evaluates explicit postconditions against independent observations after an AI agent, automation, robot, or autonomous system acts. It distinguishes a successful command from a verified outcome, uses deterministic verdict logic, and produces a structured evidence report without requiring an LLM judge.
+
+## At a glance
+
+```text
+INTENT
+  |
+ACTION
+  |
+ACKNOWLEDGEMENT
+  |
+OBSERVED WORLD STATE
+  |
+POSTCONDITIONS
+  |
+VERIFIED / NOT_VERIFIED / UNCERTAIN
+```
+
+A tool call returning success is not the same as the requested state being achieved.
+
+```text
+Agent: "Safe mode entered."
+
+$ worldstate-check demo
+
+[PASS   ] command-ack
+[PASS   ] payload-power
+[FAIL   ] attitude-error
+[PASS   ] battery-soc
+
+VERDICT: NOT_VERIFIED
+Required checks: 3/4 passed
+```
+
+The command was acknowledged and the payload was powered down, but the synthetic attitude error remained outside the required bound.
+
+## Why this is useful
+
+The same verification pattern applies across software and physical autonomy:
+
+- an agent says a deployment succeeded, but the health endpoint still fails;
+- a maintenance workflow closes a job, but the measured equipment state remains outside limits;
+- a spacecraft accepts a safe-mode command, but telemetry shows the required attitude was not reached;
+- an automation reports completion, but the expected file, process, API state, or database-facing evidence is absent.
+
+WorldState Check makes the success condition explicit and evaluates observable state instead of trusting the actor's completion claim.
+
+## Check types
+
+| Type | What it verifies |
+| --- | --- |
+| `file` | existence, text assertions, SHA-256 |
+| `json` | structured state through deterministic field comparisons |
+| `metric` | JSON or CSV telemetry, thresholds, ranges, freshness |
+| `http` | status, response text, JSON response state; network access is opt-in |
+| `tcp` | endpoint reachability; network access is opt-in |
+| `command` | explicit verification commands, opt-in only |
+
+Required checks produce one of three verdicts:
+
+- `VERIFIED` when every required postcondition passes;
+- `NOT_VERIFIED` when at least one required postcondition fails;
+- `UNCERTAIN` when no required check fails but reliable evidence is unavailable for one or more required checks.
+
+## Quick start
+
+```bash
+git clone https://github.com/sylvesterkaczmarek/worldstate-check.git
+cd worldstate-check
+python -m pip install .
+worldstate-check demo
+```
+
+Run a passing synthetic scenario:
+
+```bash
+worldstate-check demo --scenario verified
+```
+
+Create a starter specification:
+
+```bash
+worldstate-check init worldstate.yaml
+```
+
+Validate it without touching any evidence source:
+
+```bash
+worldstate-check validate worldstate.yaml
+```
+
+Then verify the observed state:
+
+```bash
+worldstate-check verify worldstate.yaml
+```
+
+Specifications that intentionally contact HTTP or TCP endpoints must opt in:
+
+```bash
+worldstate-check verify deployment.yaml --allow-network
+```
+
+Write a machine-readable evidence report:
+
+```bash
+worldstate-check verify worldstate.yaml --report evidence.json
+worldstate-check verify-report evidence.json
+```
+
+## Verification specification
+
+```yaml
+version: 1
+task: spacecraft-safe-mode
+
+checks:
+  - id: payload-off
+    type: json
+    path: telemetry.json
+    field: payload.power
+    operator: eq
+    value: "off"
+
+  - id: attitude-error
+    type: metric
+    source:
+      type: json
+      path: telemetry.json
+      field: attitude.error_deg
+    operator: lte
+    value: 3.0
+
+  - id: battery-reserve
+    type: metric
+    source:
+      type: json
+      path: telemetry.json
+      field: battery.soc
+    operator: gte
+    value: 25.0
+```
+
+See [docs/specification.md](docs/specification.md) for all supported checks.
+
+## Telemetry freshness
+
+A value can be numerically valid and still be unsafe evidence if it is stale. Metric checks can require a recent timestamp:
+
+```yaml
+- id: temperature
+  type: metric
+  source:
+    type: json
+    path: telemetry.json
+    field: temperature_c
+    timestamp_field: observed_at
+    max_age_seconds: 5
+  operator: lte
+  value: 75
+```
+
+Stale required telemetry causes `NOT_VERIFIED` because the available observation does not satisfy the declared freshness postcondition.
+
+## Waiting for eventual state
+
+Some effects are asynchronous. `--wait` re-evaluates the postconditions until they pass or the timeout expires:
+
+```bash
+worldstate-check verify deployment.yaml --wait 30
+```
+
+The report records the number of attempts. Keep verification checks idempotent when using retries.
+
+## Safety boundaries
+
+WorldState Check treats the verification specification as potentially powerful input.
+
+- evidence paths are confined to the verification root by default;
+- paths outside that root require `--allow-outside-root`;
+- command checks require `--allow-command`;
+- HTTP and TCP checks require `--allow-network`;
+- commands use an argument vector with `shell=False`;
+- command checks receive only a minimal environment and do not copy raw argv or output into evidence reports;
+- HTTP evidence redacts URL credentials, query strings, and fragments;
+- specifications and evidence reads have explicit size limits.
+
+See [docs/security.md](docs/security.md).
+
+## Example physical-system checks
+
+The repository contains two runnable file-backed examples:
+
+```bash
+worldstate-check verify examples/field-maintenance.yaml
+worldstate-check verify examples/spacecraft-safe-mode.yaml
+```
+
+The first is expected to verify. The second is intentionally expected to return `NOT_VERIFIED` because the attitude-error postcondition fails.
+
+## Evidence report
+
+JSON reports include:
+
+- task and final verdict;
+- every expected and observed value;
+- required versus optional checks;
+- timing and attempt count;
+- source metadata such as evidence path, endpoint, or telemetry age;
+- a SHA-256 digest of the report payload.
+
+`worldstate-check verify-report` recomputes that digest and reports whether the saved payload still matches it. The digest is not a digital signature and does not establish the identity or trustworthiness of the evidence source.
+
+## Assurance model
+
+WorldState Check verifies declared postconditions against observations. It does not prove that sensors, endpoints, files, or other evidence sources are trustworthy or correctly calibrated. It also does not determine whether the original intent was safe.
+
+See [docs/assurance-model.md](docs/assurance-model.md) for the exact scope.
+
+## Repository layout
+
+```text
+worldstate-check/
+├── .github/workflows/ci.yml
+├── assets/social/
+├── docs/
+├── examples/
+├── src/worldstate_check/
+│   ├── checks/
+│   ├── cli.py
+│   ├── engine.py
+│   ├── loader.py
+│   ├── models.py
+│   └── report.py
+├── tests/
+├── CITATION.cff
+├── LICENSE
+├── Makefile
+├── pyproject.toml
+└── README.md
+```
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m pip install pytest
+pytest
+```
+
+The core verdict path is deterministic and does not call an LLM.
+
+## Cite this repository
+
+If you use or adapt this repository, please cite:
+
+> Kaczmarek, S. (2026). *WorldState Check*. GitHub. https://github.com/sylvesterkaczmarek/worldstate-check
+
+```bibtex
+@software{Kaczmarek_2026_WorldState_Check,
+  author = {Sylvester Kaczmarek},
+  title  = {{WorldState Check}},
+  year   = {2026},
+  url    = {https://github.com/sylvesterkaczmarek/worldstate-check}
+}
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+© **Sylvester Kaczmarek** · [https://www.sylvesterkaczmarek.com](https://www.sylvesterkaczmarek.com)

worldstate_check-0.1.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=75", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "worldstate-check"
+version = "0.1.1"
+description = "Deterministic postcondition verification for AI agents and autonomous systems."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Sylvester Kaczmarek"}]
+dependencies = ["PyYAML>=6.0.2,<7"]
+keywords = ["ai-agents", "autonomy", "verification", "assurance", "robotics", "telemetry"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://github.com/sylvesterkaczmarek/worldstate-check"
+Repository = "https://github.com/sylvesterkaczmarek/worldstate-check"
+Issues = "https://github.com/sylvesterkaczmarek/worldstate-check/issues"
+
+[project.scripts]
+worldstate-check = "worldstate_check.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

worldstate_check-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

worldstate_check-0.1.1/src/worldstate_check/__init__.py

@@ -0,0 +1,3 @@
+"""WorldState Check package."""
+
+__version__ = "0.1.0"

worldstate_check-0.1.1/src/worldstate_check/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

worldstate_check-0.1.1/src/worldstate_check/checks/__init__.py

@@ -0,0 +1,15 @@
+from .command import run_command_check
+from .file import run_file_check
+from .http import run_http_check
+from .json_check import run_json_check
+from .metric import run_metric_check
+from .tcp import run_tcp_check
+
+CHECK_RUNNERS = {
+    "file": run_file_check,
+    "json": run_json_check,
+    "metric": run_metric_check,
+    "http": run_http_check,
+    "tcp": run_tcp_check,
+    "command": run_command_check,
+}