openmapstack 0.2.0__tar.gz → 0.3.0__tar.gz

{openmapstack-0.2.0/openmapstack.egg-info → openmapstack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openmapstack
-Version: 0.2.0
+Version: 0.3.0
 Summary: Validate, run, and inspect reproducible OpenMapStack projects
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -11,8 +11,10 @@ Provides-Extra: geo
 Requires-Dist: duckdb>=1.2; extra == "geo"
 Provides-Extra: visual
 Requires-Dist: playwright>=1.40; extra == "visual"
+Provides-Extra: postgis
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgis"
 Provides-Extra: all
-Requires-Dist: openmapstack[geo,visual]; extra == "all"
+Requires-Dist: openmapstack[geo,postgis,visual]; extra == "all"
 Dynamic: license-file
 
 # openmapstack
@@ -33,6 +35,7 @@ It is open-first and cloud-native by default, built on shoulders of the awesome
 - [SKILL.md](SKILL.md) — the skill entry point: triggers, global defaults, format and compute decision matrices, anti-patterns, and a quick triage guide.
 - [references/data-sources.md](references/data-sources.md) - lists OSM, Overture, Sentinel/Landsat, regional portals, STAC catalogs and others.
 - [references/services-and-scale.md](references/services-and-scale.md) - depending on case use local installs or hosted/SaaS services for global-scale basemaps, elevation, routing, geocoding, place search, and postcodes.
+- [references/user-data-sources.md](references/user-data-sources.md) - the user's own warehouse data: credentials by reference, read-only discovery, approval-gated snapshots, and the pin classes that make a warehouse table reproducible.
 - [references/formats-and-crs.md](references/formats-and-crs.md) - how to choose formats, conversions, projections, EPSG codes.
 - [references/processing.md](references/processing.md) - when and how to use GDAL/OGR, GeoPandas, xarray, DuckDB, PostGIS, PDAL and other open geo processing tools.
 - [references/analytics.md](references/analytics.md) — do vector/raster analytics, terrain, hydrology, network, point clouds, geocoding etc.
@@ -44,6 +47,7 @@ It is open-first and cloud-native by default, built on shoulders of the awesome
 - [examples/tartu-development/](examples/tartu-development/) — a fully-worked reproducible project matching the acceptance scenario: source provenance + timestamps, explicit assumptions, two verified project overrides (a scenario attribute change with prior-value verification, and hypothetical scenario geometry), deterministic pipeline, machine-readable validation, and semantic presentation.
 - [evals/](evals/) — the eval suite grading whether an agent reaches the right analytical answer, respects the GIS-method guardrails, and reruns reproducibly, with the `openmapstack-project/v1` contract as the substrate that makes those independently checkable: `python evals/run.py --mode fixture` runs deterministic, no-LLM checks against real generated artifacts (analytical correctness against known geospatial truth, metric CRS, source immutability, schema, overrides, validation integrity, presentation contract, and clean reruns), plus adversarial cases and a pluggable live-agent benchmark (Claude Code, Codex, and any OpenAI-compatible API such as OpenRouter — URL and model via `OPENAI_COMPATIBLE_*` env, API key as a secret).
 - [`openmapstack/`](openmapstack/) — the installable `openmapstack validate/run/inspect` CLI for auditing and executing `openmapstack-project/v1` projects, plus [`openmapstack/checks/`](openmapstack/checks/): the reusable, semantic check library. All but five of its checks are oracle-free, so the same functions that grade the eval suite also grade a user's own project on data this repository has never seen.
+- [docs/openmapbench-interop.md](docs/openmapbench-interop.md) — the narrow, versioned contract a benchmark harness such as OpenMapBench consumes: `openmapstack checks` / `check` / `api-info` (`openmapstack-check-api/v1`), the packaged result schemas, skill snapshots, arm provenance, and exported task bundles.
 - [`.claude-plugin/`](.claude-plugin/) — Claude Code plugin and marketplace manifests, so the repository can also be installed with `/plugin install`. Validated in CI by [`.github/workflows/plugin.yml`](.github/workflows/plugin.yml).
 
 My local Estonia-specific guidance (Maa- ja Ruumiamet, ETAK, EPSG:3301 / L-EST97) is included for convenience. But all the global sources are incuded for world-wide coverage.
@@ -168,6 +172,15 @@ openmapstack run path/to/project.yaml
 
 # Review sources, versions, overrides, ordered steps, outputs, and latest run.
 openmapstack inspect path/to/project.yaml
+
+# Copy SKILL.md, references/, and templates/ into a hashed, inspectable snapshot.
+openmapstack skill-snapshot --out /tmp/oms-skill --json
+openmapstack skill-snapshot --inspect /tmp/oms-skill
+
+# Read-only discovery of a warehouse source, then an approval-gated snapshot.
+openmapstack source discover path/to/project.yaml --source parcels
+openmapstack source snapshot path/to/project.yaml --source parcels \
+  --query "SELECT id, geom FROM cadastre.parcels" --destination data/source/parcels.parquet --approve
 ```
 
 Useful automation options:
@@ -193,6 +206,7 @@ PyQGIS is available.
 ```bash
 openmapstack verify path/to/project.yaml
 openmapstack verify path/to/project.yaml --rerun     # + rebuild from source and compare
+openmapstack verify path/to/project.yaml --metamorphic   # + run declared no-oracle relations
 openmapstack verify path/to/project.yaml --json --output validation/verify-report.json
 openmapstack verify path/to/project.yaml --strict    # warnings and not-testable also return 1
 ```
@@ -234,6 +248,24 @@ inputs, or a retained local evidence file invalidates the attestation and
 returns it to warning status. See
 [the project contract](references/project-spec.md#26-validation).
 
+Where no golden answer exists at all, `validation.metamorphic[]` declares
+relations that must hold under a controlled perturbation: shuffle a source and
+the result must not change, duplicate every feature and a keyed set must not
+change, widen an inclusion buffer and no candidate may disappear. Each relation
+states the precondition that makes it valid, is executed by
+`verify --metamorphic` in an isolated copy against the project's own pipeline,
+and reports `not_testable` with the reason when the precondition does not hold
+on the actual data. See [the project contract](references/project-spec.md#26-validation).
+
+`openmapstack source` is the connector pilot for the user's own data
+(DuckDB local files and PostGIS). Credentials are referenced, never stored;
+discovery is read-only with a statement timeout; a snapshot is a dry run
+until `--approve`, is limited by rows and bytes, lands only under
+`data/source/`, and hands back the `pin` block that makes the source
+reproducible. A warehouse table with only a timestamp is not pinned; an
+expired backend snapshot is reported as `not_reproducible`. See
+[user data sources](references/user-data-sources.md).
+
 `validate` checks manifest structure, source retrieval/version/licensing data,
 CRS declarations, processing graph resolution, override provenance and files,
 output existence, validation-report parity/status propagation, override

openmapstack-0.2.0/PKG-INFO → openmapstack-0.3.0/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.4
-Name: openmapstack
-Version: 0.2.0
-Summary: Validate, run, and inspect reproducible OpenMapStack projects
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: jsonschema<5,>=4
-Requires-Dist: PyYAML<7,>=6
-Provides-Extra: geo
-Requires-Dist: duckdb>=1.2; extra == "geo"
-Provides-Extra: visual
-Requires-Dist: playwright>=1.40; extra == "visual"
-Provides-Extra: all
-Requires-Dist: openmapstack[geo,visual]; extra == "all"
-Dynamic: license-file
-
 # openmapstack
 
 **Geospatial questions →  reproducible, validated GIS analysis project (with very nice interactive map).**
@@ -33,6 +16,7 @@ It is open-first and cloud-native by default, built on shoulders of the awesome
 - [SKILL.md](SKILL.md) — the skill entry point: triggers, global defaults, format and compute decision matrices, anti-patterns, and a quick triage guide.
 - [references/data-sources.md](references/data-sources.md) - lists OSM, Overture, Sentinel/Landsat, regional portals, STAC catalogs and others.
 - [references/services-and-scale.md](references/services-and-scale.md) - depending on case use local installs or hosted/SaaS services for global-scale basemaps, elevation, routing, geocoding, place search, and postcodes.
+- [references/user-data-sources.md](references/user-data-sources.md) - the user's own warehouse data: credentials by reference, read-only discovery, approval-gated snapshots, and the pin classes that make a warehouse table reproducible.
 - [references/formats-and-crs.md](references/formats-and-crs.md) - how to choose formats, conversions, projections, EPSG codes.
 - [references/processing.md](references/processing.md) - when and how to use GDAL/OGR, GeoPandas, xarray, DuckDB, PostGIS, PDAL and other open geo processing tools.
 - [references/analytics.md](references/analytics.md) — do vector/raster analytics, terrain, hydrology, network, point clouds, geocoding etc.
@@ -44,6 +28,7 @@ It is open-first and cloud-native by default, built on shoulders of the awesome
 - [examples/tartu-development/](examples/tartu-development/) — a fully-worked reproducible project matching the acceptance scenario: source provenance + timestamps, explicit assumptions, two verified project overrides (a scenario attribute change with prior-value verification, and hypothetical scenario geometry), deterministic pipeline, machine-readable validation, and semantic presentation.
 - [evals/](evals/) — the eval suite grading whether an agent reaches the right analytical answer, respects the GIS-method guardrails, and reruns reproducibly, with the `openmapstack-project/v1` contract as the substrate that makes those independently checkable: `python evals/run.py --mode fixture` runs deterministic, no-LLM checks against real generated artifacts (analytical correctness against known geospatial truth, metric CRS, source immutability, schema, overrides, validation integrity, presentation contract, and clean reruns), plus adversarial cases and a pluggable live-agent benchmark (Claude Code, Codex, and any OpenAI-compatible API such as OpenRouter — URL and model via `OPENAI_COMPATIBLE_*` env, API key as a secret).
 - [`openmapstack/`](openmapstack/) — the installable `openmapstack validate/run/inspect` CLI for auditing and executing `openmapstack-project/v1` projects, plus [`openmapstack/checks/`](openmapstack/checks/): the reusable, semantic check library. All but five of its checks are oracle-free, so the same functions that grade the eval suite also grade a user's own project on data this repository has never seen.
+- [docs/openmapbench-interop.md](docs/openmapbench-interop.md) — the narrow, versioned contract a benchmark harness such as OpenMapBench consumes: `openmapstack checks` / `check` / `api-info` (`openmapstack-check-api/v1`), the packaged result schemas, skill snapshots, arm provenance, and exported task bundles.
 - [`.claude-plugin/`](.claude-plugin/) — Claude Code plugin and marketplace manifests, so the repository can also be installed with `/plugin install`. Validated in CI by [`.github/workflows/plugin.yml`](.github/workflows/plugin.yml).
 
 My local Estonia-specific guidance (Maa- ja Ruumiamet, ETAK, EPSG:3301 / L-EST97) is included for convenience. But all the global sources are incuded for world-wide coverage.
@@ -168,6 +153,15 @@ openmapstack run path/to/project.yaml
 
 # Review sources, versions, overrides, ordered steps, outputs, and latest run.
 openmapstack inspect path/to/project.yaml
+
+# Copy SKILL.md, references/, and templates/ into a hashed, inspectable snapshot.
+openmapstack skill-snapshot --out /tmp/oms-skill --json
+openmapstack skill-snapshot --inspect /tmp/oms-skill
+
+# Read-only discovery of a warehouse source, then an approval-gated snapshot.
+openmapstack source discover path/to/project.yaml --source parcels
+openmapstack source snapshot path/to/project.yaml --source parcels \
+  --query "SELECT id, geom FROM cadastre.parcels" --destination data/source/parcels.parquet --approve
 ```
 
 Useful automation options:
@@ -193,6 +187,7 @@ PyQGIS is available.
 ```bash
 openmapstack verify path/to/project.yaml
 openmapstack verify path/to/project.yaml --rerun     # + rebuild from source and compare
+openmapstack verify path/to/project.yaml --metamorphic   # + run declared no-oracle relations
 openmapstack verify path/to/project.yaml --json --output validation/verify-report.json
 openmapstack verify path/to/project.yaml --strict    # warnings and not-testable also return 1
 ```
@@ -234,6 +229,24 @@ inputs, or a retained local evidence file invalidates the attestation and
 returns it to warning status. See
 [the project contract](references/project-spec.md#26-validation).
 
+Where no golden answer exists at all, `validation.metamorphic[]` declares
+relations that must hold under a controlled perturbation: shuffle a source and
+the result must not change, duplicate every feature and a keyed set must not
+change, widen an inclusion buffer and no candidate may disappear. Each relation
+states the precondition that makes it valid, is executed by
+`verify --metamorphic` in an isolated copy against the project's own pipeline,
+and reports `not_testable` with the reason when the precondition does not hold
+on the actual data. See [the project contract](references/project-spec.md#26-validation).
+
+`openmapstack source` is the connector pilot for the user's own data
+(DuckDB local files and PostGIS). Credentials are referenced, never stored;
+discovery is read-only with a statement timeout; a snapshot is a dry run
+until `--approve`, is limited by rows and bytes, lands only under
+`data/source/`, and hands back the `pin` block that makes the source
+reproducible. A warehouse table with only a timestamp is not pinned; an
+expired backend snapshot is reported as `not_reproducible`. See
+[user data sources](references/user-data-sources.md).
+
 `validate` checks manifest structure, source retrieval/version/licensing data,
 CRS declarations, processing graph resolution, override provenance and files,
 output existence, validation-report parity/status propagation, override

{openmapstack-0.2.0 → openmapstack-0.3.0}/openmapstack/__init__.py

@@ -3,4 +3,4 @@
 from .validation import Check, ValidationResult, validate_project
 
 __all__ = ["Check", "ValidationResult", "validate_project"]
-__version__ = "0.2.0"
+__version__ = "0.3.0"

openmapstack-0.3.0/openmapstack/api.py

@@ -0,0 +1,319 @@
+"""The versioned check API that external harnesses consume.
+
+OpenMapBench (and any other benchmark or CI system) grades produced projects
+with this package's checks. It must be able to do so without vendoring the
+check implementations and without depending on module layout: the surface
+it may rely on is exactly
+
+- ``CHECK_API_VERSION`` and ``api_info()`` for negotiation;
+- ``list_checks()`` for the catalogue of check names and their parameters;
+- ``run_check()`` for one check, returning a record that validates against
+  ``openmapstack-check-result/v1``;
+- ``openmapstack verify --json``, returning ``openmapstack-verify-result/v1``;
+- the JSON schemas packaged under ``openmapstack/schemas/``.
+
+Everything else in ``openmapstack.checks`` is implementation.
+
+Versioning: ``CHECK_API_VERSION`` follows ``<name>/v<major>``. A new check,
+a new optional parameter, or a new result field is additive and does not
+change the major. Renaming or removing a check, changing a parameter's
+meaning, or changing the four-state status vocabulary does. A consumer
+pins the major and the minimum package version it was tested against, and
+``negotiate()`` answers whether the installed package satisfies both.
+
+Result semantics that a consumer may rely on:
+
+- ``status`` is one of ``passed | failed | warning | not_testable`` and a
+  check that could not establish its predicate is never ``passed``;
+- ``code`` is a stable machine-readable identifier when the status is not
+  ``passed``; consumers grade on ``status`` and, for mutation-style
+  expectations, ``code`` -- never on ``detail`` text;
+- ``dimension`` is the reporting bucket the check belongs to; buckets are
+  reported separately and must not be collapsed into one score;
+- ``oracle_free`` is ``false`` for the checks that need a known answer.
+  Those transfer to arbitrary data only through attested expectations.
+
+Setup failures (a check that raises) are reported as ``not_testable`` with
+``code: check_error`` by ``run_check`` so a broken environment cannot
+produce either a pass or a graded failure; benchmark harnesses keep them
+out of scored denominators.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .checks import STATUSES, AssertionResult, not_testable
+from .schema import validation_errors
+
+CHECK_API_VERSION = "openmapstack-check-api/v1"
+CHECK_RESULT_SCHEMA = "openmapstack-check-result/v1"
+API_INFO_SCHEMA = "openmapstack-api-info/v1"
+VERIFY_RESULT_SCHEMA = "openmapstack-verify-result/v1"
+PROJECT_SCHEMA = "openmapstack-project/v1"
+
+CHECK_MODULES = (
+    "project",
+    "provenance",
+    "overrides",
+    "validation",
+    "geodata",
+    "presentation",
+    "qgis",
+    "visual",
+    "rerun",
+    "metamorphic",
+)
+
+# Reporting buckets. Shared with evals/run.py, which asserts equality in
+# tests so the two cannot drift apart.
+DIMENSIONS = {
+    "project": "reproducibility_compliance",
+    "overrides": "override_handling",
+    "provenance": "provenance",
+    "geodata": "gis_correctness",
+    "validation": "validation_integrity",
+    "qgis": "presentation_contract",
+    "presentation": "presentation_contract",
+    "visual": "visual_judgement",
+    "rerun": "rerun_success",
+    "metamorphic": "metamorphic_evidence",
+}
+
+# The checks that need a known answer. They are reachable on user data
+# only through validation.expectations[] attestations.
+KNOWN_ANSWER_CHECKS = frozenset(
+    {
+        "geodata.row_count",
+        "geodata.feature_present",
+        "geodata.feature_absent",
+        "geodata.feature_field_equals",
+        "geodata.field_range",
+    }
+)
+
+_SCHEMA_DIR = Path(__file__).resolve().parent / "schemas"
+_VERSION = re.compile(r"^(\d+)\.(\d+)\.(\d+)")
+
+
+class CheckAPIError(ValueError):
+    """The consumer asked for something the API does not provide."""
+
+
+@dataclass(frozen=True)
+class CheckParameter:
+    name: str
+    required: bool
+    default: Any = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"name": self.name, "required": self.required}
+        if not self.required:
+            payload["default"] = self.default
+        return payload
+
+
+@dataclass(frozen=True)
+class CheckDescriptor:
+    name: str
+    module: str
+    dimension: str
+    oracle_free: bool
+    summary: str
+    parameters: tuple[CheckParameter, ...] = field(default_factory=tuple)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "module": self.module,
+            "dimension": self.dimension,
+            "oracle_free": self.oracle_free,
+            "summary": self.summary,
+            "parameters": [parameter.to_dict() for parameter in self.parameters],
+        }
+
+
+def _load_schema(name: str) -> dict[str, Any]:
+    return json.loads((_SCHEMA_DIR / name).read_text(encoding="utf-8"))
+
+
+def _describe(module_name: str, function_name: str, function: Any) -> CheckDescriptor:
+    signature = inspect.signature(function)
+    parameters: list[CheckParameter] = []
+    for index, parameter in enumerate(signature.parameters.values()):
+        if index == 0:  # workspace
+            continue
+        if parameter.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+        required = parameter.default is inspect.Parameter.empty
+        default = None if required else parameter.default
+        if isinstance(default, tuple):
+            default = list(default)
+        parameters.append(CheckParameter(parameter.name, required, default))
+    doc = inspect.getdoc(function) or ""
+    summary = doc.strip().splitlines()[0].strip() if doc.strip() else ""
+    name = f"{module_name}.{function_name}"
+    return CheckDescriptor(
+        name=name,
+        module=module_name,
+        dimension=DIMENSIONS.get(module_name, "other"),
+        oracle_free=name not in KNOWN_ANSWER_CHECKS,
+        summary=summary,
+        parameters=tuple(parameters),
+    )
+
+
+def _is_check(function: Any) -> bool:
+    if not inspect.isfunction(function) or function.__name__.startswith("_"):
+        return False
+    try:
+        parameters = list(inspect.signature(function).parameters.values())
+    except (TypeError, ValueError):
+        return False
+    return bool(parameters) and parameters[0].name == "workspace"
+
+
+def list_checks() -> list[CheckDescriptor]:
+    """Every public check, discovered from the shipped modules."""
+    descriptors: list[CheckDescriptor] = []
+    for module_name in CHECK_MODULES:
+        module = importlib.import_module(f"openmapstack.checks.{module_name}")
+        for function_name, function in sorted(vars(module).items()):
+            if getattr(function, "__module__", None) != module.__name__:
+                continue
+            if _is_check(function):
+                descriptors.append(_describe(module_name, function_name, function))
+    return descriptors
+
+
+def describe_check(name: str) -> CheckDescriptor:
+    module_name, _, function_name = name.partition(".")
+    function = _resolve(name)
+    if getattr(function, "__module__", None) != f"openmapstack.checks.{module_name}":
+        raise CheckAPIError(f"unknown check {name!r}; see list_checks()")
+    return _describe(module_name, function_name, function)
+
+
+def _resolve(name: str) -> Any:
+    module_name, _, function_name = name.partition(".")
+    if module_name not in CHECK_MODULES or not function_name:
+        raise CheckAPIError(f"unknown check {name!r}; see list_checks()")
+    module = importlib.import_module(f"openmapstack.checks.{module_name}")
+    function = getattr(module, function_name, None)
+    if function is None or not _is_check(function):
+        raise CheckAPIError(f"unknown check {name!r}; see list_checks()")
+    return function
+
+
+def run_check(name: str, workspace: str | Path, args: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Execute one check and return an ``openmapstack-check-result/v1`` record.
+
+    Unknown check names and malformed arguments raise ``CheckAPIError``
+    (a consumer configuration error). A check that raises while running is
+    reported as ``not_testable`` with ``code: check_error`` -- never as a
+    pass, and never as a graded failure.
+    """
+    descriptor = describe_check(name)
+    function = _resolve(name)
+    args = dict(args or {})
+    declared = {parameter.name for parameter in descriptor.parameters}
+    unknown = sorted(set(args) - declared)
+    missing = sorted(parameter.name for parameter in descriptor.parameters if parameter.required and parameter.name not in args)
+    if unknown or missing:
+        raise CheckAPIError(f"{name}: unknown args {unknown}, missing required args {missing}")
+    try:
+        result = function(Path(workspace), **args)
+    except Exception as exc:  # noqa: BLE001 - a check must never take a harness down
+        result = not_testable(f"{type(exc).__name__}: {exc}", code="check_error")
+    if not isinstance(result, AssertionResult) or result.status not in STATUSES:
+        result = not_testable("check returned a malformed result", code="check_error")
+    data = {key: value for key, value in result.data.items() if key != "code"}
+    record: dict[str, Any] = {
+        "schema": CHECK_RESULT_SCHEMA,
+        "api_version": CHECK_API_VERSION,
+        "package_version": __version__,
+        "check": name,
+        "dimension": descriptor.dimension,
+        "oracle_free": descriptor.oracle_free,
+        "args": args,
+        "status": result.status,
+        "code": result.data.get("code"),
+        "detail": result.detail,
+        "data": json.loads(json.dumps(data, default=str)),
+    }
+    errors = validation_errors(record, _load_schema("check-result-v1.schema.json"))
+    if errors:  # pragma: no cover - the record is built here; a failure is a bug
+        raise CheckAPIError(f"internal: check result does not validate: {errors}")
+    return record
+
+
+def api_info() -> dict[str, Any]:
+    """What this installation offers, for a consumer to negotiate against."""
+    checks = list_checks()
+    return {
+        "schema": API_INFO_SCHEMA,
+        "package": "openmapstack",
+        "package_version": __version__,
+        "check_api_version": CHECK_API_VERSION,
+        "project_schema": PROJECT_SCHEMA,
+        "result_schemas": {
+            "check": CHECK_RESULT_SCHEMA,
+            "verify": VERIFY_RESULT_SCHEMA,
+        },
+        "statuses": list(STATUSES),
+        "dimensions": sorted(set(DIMENSIONS.values())),
+        "checks": len(checks),
+        "oracle_free_checks": sum(descriptor.oracle_free for descriptor in checks),
+        "known_answer_checks": sorted(KNOWN_ANSWER_CHECKS),
+    }
+
+
+def _parse_version(text: str) -> tuple[int, int, int]:
+    match = _VERSION.match(text or "")
+    if match is None:
+        raise CheckAPIError(f"not a semantic version: {text!r}")
+    return tuple(int(part) for part in match.groups())  # type: ignore[return-value]
+
+
+def negotiate(
+    *,
+    required_api: str = CHECK_API_VERSION,
+    min_package_version: str | None = None,
+    required_checks: list[str] | None = None,
+) -> dict[str, Any]:
+    """Answer whether this installation satisfies a consumer's requirements.
+
+    A consumer states the API major it was built for, the oldest package
+    version it was tested against, and the checks it needs. The answer
+    lists every unmet requirement so a harness can report *why* it is
+    refusing to grade rather than grading with a checker it does not
+    understand.
+    """
+    problems: list[str] = []
+    if required_api != CHECK_API_VERSION:
+        problems.append(f"check API {required_api!r} is not provided; this package offers {CHECK_API_VERSION!r}")
+    if min_package_version is not None and _parse_version(__version__) < _parse_version(min_package_version):
+        problems.append(f"package version {__version__} is older than the required {min_package_version}")
+    available = {descriptor.name for descriptor in list_checks()}
+    missing = sorted(name for name in (required_checks or []) if name not in available)
+    if missing:
+        problems.append(f"checks not provided: {missing}")
+    return {
+        "schema": "openmapstack-api-negotiation/v1",
+        "compatible": not problems,
+        "package_version": __version__,
+        "check_api_version": CHECK_API_VERSION,
+        "problems": problems,
+    }
+
+
+def validate_verify_result(payload: dict[str, Any]) -> list[str]:
+    """Schema-validate an ``openmapstack verify --json`` document."""
+    return validation_errors(payload, _load_schema("verify-result-v1.schema.json"))

openmapstack-0.3.0/openmapstack/checks/metamorphic.py

@@ -0,0 +1,74 @@
+"""Metamorphic-relation assertions.
+
+Thin check-library entry points over ``openmapstack.metamorphic`` so an eval
+case (``assert: metamorphic.relation_holds``) and ``openmapstack verify
+--metamorphic`` grade the same thing. See that module for the relations,
+their preconditions, and the result vocabulary.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import AssertionResult, failed, load_project_yaml, not_testable, passed, project_root
+
+
+def declarations_valid(workspace: Path, project_dir: str = ".") -> AssertionResult:
+    """Every ``validation.metamorphic[]`` entry parses, names a known relation,
+    and addresses declared outputs. Structural only: nothing is executed."""
+    from ..metamorphic import DeclarationError, declared_relations, parse_declaration
+
+    proj = load_project_yaml(workspace, project_dir)
+    if proj is None:
+        return failed("project.yaml missing", code="manifest_missing")
+    try:
+        raw_declarations = declared_relations(proj)
+    except DeclarationError as exc:
+        return failed(str(exc), code="metamorphic_declaration_invalid")
+    if not raw_declarations:
+        return not_testable("no metamorphic relations are declared", code="metamorphic_undeclared")
+    errors: list[str] = []
+    seen: set[str] = set()
+    outputs = proj.get("outputs") if isinstance(proj.get("outputs"), dict) else {}
+    for raw in raw_declarations:
+        try:
+            declaration = parse_declaration(raw)
+        except DeclarationError as exc:
+            errors.append(str(exc))
+            continue
+        if declaration.id in seen:
+            errors.append(f"{declaration.id}: duplicate relation id")
+        seen.add(declaration.id)
+        missing = [key for key in declaration.outputs if key not in outputs]
+        if missing:
+            errors.append(f"{declaration.id}: outputs {missing} are not declared outputs")
+    if errors:
+        return failed("; ".join(errors), code="metamorphic_declaration_invalid")
+    return passed(f"{len(raw_declarations)} metamorphic relation(s) are well-formed")
+
+
+def relation_holds(
+    workspace: Path,
+    id: str,
+    project_dir: str = ".",
+    forbidden_fragments: list[str] | None = None,
+) -> AssertionResult:
+    """Execute the declared relation ``id`` in an isolated variant workspace."""
+    from ..metamorphic import DeclarationError, declared_relations, run_relation
+
+    root = project_root(workspace, project_dir)
+    proj = load_project_yaml(workspace, project_dir)
+    if proj is None:
+        return failed("project.yaml missing", code="manifest_missing")
+    try:
+        raw_declarations = declared_relations(proj)
+    except DeclarationError as exc:
+        return failed(str(exc), code="metamorphic_declaration_invalid")
+    matches = [raw for raw in raw_declarations if isinstance(raw, dict) and raw.get("id") == id]
+    if not matches:
+        return failed(f"no metamorphic relation with id {id!r} is declared", code="metamorphic_relation_undeclared")
+    result, evidence = run_relation(root, proj, matches[0], forbidden_fragments=tuple(forbidden_fragments or ()))
+    data: dict[str, Any] = dict(result.data)
+    data["evidence"] = evidence
+    return AssertionResult(result.status, result.detail, data)

{openmapstack-0.2.0 → openmapstack-0.3.0}/openmapstack/checks/project.py

@@ -259,3 +259,29 @@ def assumptions_have_rationale(workspace: Path, project_dir: str = ".") -> Asser
             code="assumption_missing_rationale",
         )
     return passed(f"all {len(assumptions)} assumptions have statement + rationale")
+
+
+def parameters_match_steps(workspace: Path, project_dir: str = ".") -> AssertionResult:
+    """``runtime.implementation.parameters`` is well-formed and each parameter
+    bound to a processing step agrees with that step's declared value.
+
+    A manifest that advertises one threshold under ``parameters`` while the
+    step declares another is drift of the same kind as a presentation
+    control that disagrees with the pipeline: the whole view becomes a
+    confident lie. See ``openmapstack.parameters``.
+    """
+    from ..parameters import ParameterError, declared_parameters
+
+    proj = load_project_yaml(workspace, project_dir)
+    if proj is None:
+        return failed("project.yaml missing", code="manifest_missing")
+    try:
+        parameters = declared_parameters(proj)
+    except ParameterError as exc:
+        return failed(str(exc), code="parameters_invalid")
+    if not parameters:
+        return not_testable("no runtime parameters are declared", code="parameters_undeclared")
+    bound = sum(1 for parameter in parameters if parameter.step)
+    return passed(
+        f"{len(parameters)} runtime parameter(s) declared; {bound} bound to a processing step agree with it"
+    )