# GEARM 0.1 Test Cases and Runner — GEARM-A10 / GEARM-A11 / GEARM-A12

This directory contains deterministic machine-validation fixtures for the GEARM 0.1 artifact stack.

- **GEARM-A10** establishes expected-PASS positive fixtures.
- **GEARM-A11** establishes expected-FAIL negative fixtures, separated by failure class.
- **GEARM-A12** establishes the automated machine-conformance regression runner that executes the manifest expectations.

A testcase outcome means only that the validator layer declared in `manifest.json` is expected to behave as specified. It does **not** mean that complete GEARM conformance has been established or disproved beyond the scope of that validator.

## Test identity bands

- `GEARM-TC-001..099` — positive / expected-PASS fixtures
- `GEARM-TC-100..199` — structural-invalid / expected **A7 JSON Schema FAIL**
- `GEARM-TC-200..299` — semantic-invalid / expected **A6 SHACL FAIL**
- `GEARM-TC-300..399` — Profile-invalid / expected **A8 Profile Schema FAIL**

`manifest.json` is the authoritative inventory of testcase identity, failure class, targeted artifacts/invariants and expected validator behaviour.

## GEARM-A10 positive fixtures

The established GEARM-A10 positive suite remains unchanged: `GEARM-TC-001` through `GEARM-TC-014`.

## GEARM-A11 structural-invalid fixtures

| ID | Primary invalidity | Expected result |
|---|---|---|
| GEARM-TC-100 | Undeclared GEARM concept type | A7 FAIL |
| GEARM-TC-101 | Undeclared `gearm:` relationship | A7 FAIL |
| GEARM-TC-102 | Wrong GEARM version | A7 FAIL |
| GEARM-TC-103 | Unsupported terminology mapping type | A7 FAIL |
| GEARM-TC-104 | Applicability target missing | A7 FAIL |
| GEARM-TC-105 | Nonexistent invariant reference | A7 FAIL |
| GEARM-TC-106 | Invalid conformance-result vocabulary | A7 FAIL |
| GEARM-TC-107 | Extension authority missing | A7 FAIL |
| GEARM-TC-108 | Both `graph` and `@graph` supplied | A7 FAIL |
| GEARM-TC-109 | Nonexistent relationship registry ID | A7 FAIL |

A structural-invalid fixture is invalid as a GEARM A7 representation. No semantic conclusion beyond that structural failure is implied.

## GEARM-A11 semantic-invalid fixtures

| ID | Targeted invariant | Machine-detectable violation | SHACL graph mode |
|---|---|---|---|
| GEARM-TC-200 | GEARM-INV-123 | `Recommendation` explicitly equivalent to `Decision` | canonical + fixture |
| GEARM-TC-201 | GEARM-INV-012 | `MetricDefinition` explicitly equivalent to `MetricObservation` | canonical + fixture |
| GEARM-TC-202 | GEARM-INV-048 | `Signal` explicitly equivalent to `Alert` | canonical + fixture |
| GEARM-TC-203 | GEARM-INV-070 | `Observation` explicitly equivalent to `Inference` | canonical + fixture |
| GEARM-TC-204 | GEARM-INV-125 | `Decision` explicitly equivalent to `Action` | canonical + fixture |
| GEARM-TC-205 | GEARM-INV-190 | `DefinitionGraph` explicitly equivalent to `ExecutionGraph` | canonical + fixture |
| GEARM-TC-206 | GEARM-INV-110 | `dependsOn` collapsed into `specializes` | canonical + fixture |
| GEARM-TC-207 | GEARM-INV-112 | `invokes` made a subproperty of `specializes` | canonical + fixture |
| GEARM-TC-208 | GEARM-INV-208 | `equivalentTo` collapsed into `specializes` | canonical + fixture |
| GEARM-TC-209 | GEARM-INV-076 | Candidate vocabulary omits `Forecast IS-A Prediction` | fixture only |

These fixtures are intentionally **A7-valid and JSON-LD-expandable** before A6 rejects the targeted machine-detectable semantic violation. This demonstrates the validation-layer boundary:

```text
structurally valid != semantically valid
```

An A6 failure proves only the executable portion represented by that Shape. Semantic assessment remains required where A3 classifies the invariant as Hybrid.

## GEARM-A11 Profile-invalid fixtures

| ID | Primary invalidity | Expected result |
|---|---|---|
| GEARM-TC-300 | Missing `profiles` binding | A8 FAIL |
| GEARM-TC-301 | Wrong GEARM version | A8 FAIL |
| GEARM-TC-302 | Canonical GEARM namespace reused | A8 FAIL |
| GEARM-TC-303 | `Not Applicable` without reason | A8 FAIL |
| GEARM-TC-304 | Core `SHALL` invariant used as a tightening target | A8 FAIL |
| GEARM-TC-305 | Tightening level is not `SHALL` | A8 FAIL |
| GEARM-TC-306 | Unknown canonical concept | A8 FAIL |
| GEARM-TC-307 | Unknown canonical relationship | A8 FAIL |
| GEARM-TC-308 | Cardinality constraint lacks min/max | A8 FAIL |
| GEARM-TC-309 | Profile attempts to carry `deviations` | A8 FAIL |
| GEARM-TC-310 | Invalid external-spec conformance mode | A8 FAIL |
| GEARM-TC-311 | Evidence `supports` list is empty | A8 FAIL |

## Validation layers

The manifest uses these result vocabularies:

- `jsonSchema`: `pass`, `fail`, `not-run`
- `jsonLdExpansion`: `pass`, `fail`, `not-run`
- `shacl`: `pass`, `fail`, `not-run`
- `profileSchema`: `pass`, `fail`, `not-run`
- `semanticAssessment`: `required`, `not-required`, `not-applicable`
- `completeConformance`: `not-claimed`

For semantic JSON-LD cases, `shaclGraphMode` declares whether A6 validates the canonical A4 graph plus the testcase graph or a deliberately incomplete candidate vocabulary graph by itself.

## GEARM-A12 automated runner

`run_conformance.py` is the packaged executable oracle for the A10/A11 manifest. It runs entirely against local packaged artifacts and does not require network access. The baseline dependencies are listed in `requirements-conformance.txt`.

Run the complete suite from `static/specs/gearm/0.1/`:

```bash
python testcases/run_conformance.py --suite
```

Useful selections:

```bash
python testcases/run_conformance.py --band positive
python testcases/run_conformance.py --band semantic-invalid
python testcases/run_conformance.py --case GEARM-TC-200
python testcases/run_conformance.py --list
python testcases/run_conformance.py --suite --json-report gearm-a12-report.json
```

The default SHACL engine is `native`. It executes exactly the SHACL feature subset currently used by A6: `sh:targetNode`, SHACL-SPARQL `sh:select`, and `sh:property` with `sh:path` + `sh:hasValue`. Before validation it checks the A6 shape graph and **fails closed** if an unsupported SHACL construct appears, preventing future constraints from being silently skipped.

An optional standards-engine cross-check may be requested with:

```bash
python testcases/run_conformance.py --suite --shacl-engine pyshacl
```

when `pyshacl` is installed. `--shacl-engine auto` selects PySHACL when available and otherwise uses the packaged native engine.

GEARM semantic graph documents can use an identified top-level `@graph`. JSON-LD therefore materializes testcase content into named graphs. A12 parses JSON-LD as a dataset and validates the union of its quads, so the semantic content of named graphs is included in A6 validation. Relative packaged contexts are inlined before expansion to keep execution deterministic and offline.

Exit codes are:

- `0` — all selected machine expectations matched the manifest;
- `2` — dependency, package, manifest, or runner execution error;
- `3` — one or more actual machine outcomes did not match the manifest.

A runner `PASS` means **machine regression expectations matched**. It does not perform human semantic assessment and does not establish complete GEARM conformance where the manifest records `semanticAssessment: required`.