Metadata-Version: 2.4
Name: valid8x
Version: 0.6.0
Summary: Valid8X — JSON Schema 2020-12 validator that emits a signed, replayable evidence receipt (canonical payload + SBOM + HMAC-signed provenance token) for every run.
Author-email: AlphaBeta Studios LLC <zgutche@alphabetastudiosllc.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/AlphaBeta-Labs/VALIDX
Project-URL: Repository, https://github.com/AlphaBeta-Labs/VALIDX
Project-URL: Issues, https://github.com/AlphaBeta-Labs/VALIDX/issues
Keywords: json-schema,validation,compliance,governance,sbom,provenance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema==4.25.1
Requires-Dist: PyYAML==6.0.3
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Dynamic: license-file

# Valid8X

**JSON Schema validation that emits a signed receipt for every run.**

[![PyPI](https://img.shields.io/pypi/v/valid8x.svg)](https://pypi.org/project/valid8x/)
[![Python](https://img.shields.io/pypi/pyversions/valid8x.svg)](https://pypi.org/project/valid8x/)
[![License](https://img.shields.io/pypi/l/valid8x.svg)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/AlphaBeta-Labs/ValidX/ci.yml?branch=main)](https://github.com/AlphaBeta-Labs/ValidX/actions)
[![Schema](https://img.shields.io/badge/JSON%20Schema-2020--12-blue.svg)](https://json-schema.org/draft/2020-12/release-notes)
[![Receipt](https://img.shields.io/badge/receipts-HMAC%20%2B%20SHA--256-green.svg)](DOCS/VERIFY_REPORT_SCHEMA.md)

Most Python JSON Schema validators return `True` or a list of errors and forget the run ever happened. That's an opinion, not evidence.

Valid8X is a deterministic JSON Schema 2020-12 validator that writes a signed, replayable receipt for every validation: canonicalized payload, full error trace, CycloneDX SBOM of the validator's own dependency closure, and an HMAC-signed provenance token. Archive it. Replay it. Defend it in an audit.

It also has a governed repair mode — bounded subprocess fixer attempts under an explicit permit file — so the LLM repair path is auditable instead of a black box.

## Quickstart

```bash
pip install valid8x
validx validate --registry examples/CONTRACTS/schemas/_registry.json \
                --schema-key example.person \
                --input examples/person_bad.yaml \
                --out-dir out
cat out/verify_report.json   # your signed receipt
```

## Naming

Valid8X follows the same "distribution name vs import name" pattern as
Pillow (PyPI `Pillow`, import `PIL`) and BeautifulSoup (PyPI `beautifulsoup4`,
import `bs4`). This is intentional.

| Surface | Name |
|---|---|
| PyPI distribution | `valid8x` — `pip install valid8x` |
| Python import / CLI binary | `validx` — `from validx import …`, `validx --help` |
| Canonical source | `RELEASEPROOF/validx/` (monorepo) |
| Public read-only mirror | `github.com/AlphaBeta-Labs/Valid8x` |
| Product brand | Valid8X |

The PyPI name uses `8` because `validx` was unavailable on PyPI. Internal
callers (Kinetic, ReleaseProof) import `validx` directly from the monorepo
source. External users `pip install valid8x` and get the same module under
`import validx`.

## Feature availability

| Feature                          | Since  |
|----------------------------------|--------|
| Deterministic validate           | 0.1    |
| HMAC-signed provenance receipt   | 0.2    |
| CycloneDX SBOM emission          | 0.3    |
| Subprocess fixer (repair mode)   | 0.3    |
| verify-report-validate CLI       | 0.4    |
| GitHub Action / pre-commit / MCP | 0.5    |
| VSCode extension                 | 0.5    |
| Schema inferencer                | 0.6    |
| Signed release artifacts (cosign)| 0.6    |

## Why

- **Replayable.** Re-run validation against the receipt; get a byte-identical result or a loud failure.
- **Auditable.** Every run carries its own SBOM and a provenance token tied to schema registry version + input bytes.
- **Governed AI repair.** Permit file declares exactly which mutations are allowed. Unknown fields rejected. No silent scope expansion.
- **Deterministic.** Canonicalization rules are documented and versioned. No "works on my machine."

## Architecture Note

- Structural Integrity Membrane model: `DOCS/VALIDX_MEMBRANE.md`

## Installed Modes

- `validate`: deterministic validation only
- `explain`: deterministic validation + explanation object, no AI
- `repair`: deterministic repair in v0.3 with bounded subprocess fixer attempts (v0.4 adds report validation CLI hardening and packaging artifacts)
- `extract`: deterministic extraction scaffold (permit-gated, not implemented)

## CLI

```bash
validx validate --registry examples/CONTRACTS/schemas/_registry.json --schema-key example.person --input examples/person_bad.yaml --out-dir out --approved-root examples
validx explain --registry examples/CONTRACTS/schemas/_registry.json --schema-key example.person --input examples/person_bad.yaml --out-dir out --approved-root examples
validx repair  --registry examples/CONTRACTS/schemas/_registry.json --schema-key example.person --input examples/person_bad.yaml --out-dir out --approved-root examples --permit-path examples/permit.json --ai-driver subprocess --ai-model-id fake-fixer-v1 --ai-cmd "python -m tests.fake_fixer_runner"
validx extract --registry examples/CONTRACTS/schemas/_registry.json --schema-key example.person --input examples/person_bad.yaml --out-dir out --approved-root examples --permit-path examples/permit.json
validx verify-report-validate \
  --verify-report out/verify_report.json \
  --report-schema CONTRACTS/schemas/validx/verify_report_v1.schema.json \
  --out out/verify_report_validation.json
validx permit-validate \
  --permit examples/permits/structural_only.json \
  --permit-schema CONTRACTS/schemas/validx/permit_v1.schema.json \
  --out out/permit_validation.json
validx tool-manifest-validate \
  --tool-manifest path/to/validx_tool_manifest.json \
  --manifest-schema CONTRACTS/schemas/validx/tool_manifest_v1.schema.json \
  --out out/tool_manifest_validation.json
validx doctor
validx doctor --text
validx doctor --run-pip-check
validx doctor --run-pip-audit
validx sbom --format validx
validx sbom --format cyclonedx
validx sbom --format cyclonedx --cyclonedx-require-pin --cyclonedx-manifest CONTRACTS/tools/cyclonedx/cyclonedx_py.pin.json
validx sbom-tool-receipt
validx contract-snapshot
validx secrets-scan
validx latency-trend-refresh --metrics /tmp/validx_sweep_gate_metrics.json
validx promote-precheck
validx artifact-integrity-check
validx graph-ir-gate --graph-ir CONTRACTS/tools/provenance/graph_ir_v1.json
validx intake-check --rights-lineage CONTRACTS/tools/provenance/rights_lineage_v1.json --graph-ir CONTRACTS/tools/provenance/graph_ir_v1.json
validx provenance-check --token CONTRACTS/tools/provenance/provenance_token_v1.json --rights-lineage CONTRACTS/tools/provenance/rights_lineage_v1.json --graph-ir CONTRACTS/tools/provenance/graph_ir_v1.json --action mirror_export
validx provenance-sign --token CONTRACTS/tools/provenance/provenance_token_v1.json --key-env VALIDX_PROVENANCE_HMAC_KEY
```

## Permit

Permit files are JSON objects with only these boolean fields:
- `semantic_repair`
- `extraction`
- `allow_defaults`
- `allow_drop_fields`

Unknown fields are rejected. Boolean coercion is not performed.
# Packaging assets

Build locally with:

```bash
python3 scripts/package_bundle.py --out validx_v1_scaffold_bundle_v0_4_2.zip
sha256sum validx_v1_scaffold_bundle_v0_4_2.zip > validx_v1_scaffold_bundle_v0_4_2.zip.sha256
```

Bundles are never committed to the repository. Build artifacts are local-only.

## Sweep Gate (one command)

```bash
bash scripts/sweep_gate.sh
```

This runs install/tests/build plus a small validator-cache performance smoke.
It also emits:
- metrics JSON: `${VALIDX_GATE_METRICS_PATH:-/tmp/validx_sweep_gate_metrics.json}`
- gate receipt JSON: `${VALIDX_GATE_RECEIPT_PATH:-artifacts/gate_receipt.json}`
- deterministic SBOM JSON: `${VALIDX_GATE_SBOM_PATH:-artifacts/sbom_validx_v1.json}`
- deterministic SBOM hash receipt: `${VALIDX_GATE_SBOM_PATH:-artifacts/sbom_validx_v1.json}.sha256`
- CycloneDX tool pin receipt: `${VALIDX_GATE_SBOM_TOOL_RECEIPT_PATH:-artifacts/sbom_tool_receipt.json}`
- deterministic contract snapshot JSON: `${VALIDX_GATE_CONTRACT_SNAPSHOT_PATH:-artifacts/contract_snapshot_v1.json}`
- deterministic contract snapshot hash receipt: `${VALIDX_GATE_CONTRACT_SNAPSHOT_PATH:-artifacts/contract_snapshot_v1.json}.sha256`
- secrets scan JSON: `${VALIDX_GATE_SECRETS_SCAN_PATH:-artifacts/secrets_scan_v1.json}`
- secrets scan hash receipt: `${VALIDX_GATE_SECRETS_SCAN_PATH:-artifacts/secrets_scan_v1.json}.sha256`
- promotion precheck JSON (promotion profile or `VALIDX_GATE_REQUIRE_PROMOTE_PRECHECK=1`): `${VALIDX_GATE_PROMOTE_PRECHECK_PATH:-artifacts/promote_precheck_v1.json}`
- artifact integrity JSON (promotion profile or `VALIDX_GATE_REQUIRE_ARTIFACT_INTEGRITY=1`): `${VALIDX_GATE_ARTIFACT_INTEGRITY_PATH:-artifacts/artifact_integrity_v1.json}`
- optional strict CycloneDX JSON (when `VALIDX_GATE_REQUIRE_CYCLONEDX=1`): `${VALIDX_GATE_CYCLONEDX_PATH:-artifacts/sbom_cyclonedx.json}`
  - receipt also publishes `cyclonedx.manifest_ready` and `cyclonedx.manifest_reason` for strict-pin readiness

## Two-Tier Mirror Export

ValidX runs as:
- private authoritative core (trade-secret governance membrane)
- generated public mirror (interoperability surface only)

Mirror policy and controls:
- policy: `MIRROR_POLICY.yaml`
- exporter: `scripts/mirror_export.sh`
- leak checker: `scripts/check_mirror_leak.sh`
- guardrail docs: `DOCS/MIRROR_POLICY.md`

## Defensive limits

- JSON config/schema/report documents are capped at `8 MiB`.
- Input payload files/bytes are capped at `16 MiB`.
- Subprocess fixer request payload is capped at `16 MiB`.
- Subprocess fixer output payload is capped at `16 MiB`.

Policy overrides are supported via env vars (or optional JSON policy file via `VALIDX_POLICY_FILE`, or CLI `--policy`):
- `VALIDX_MAX_JSON_DOC_BYTES`
- `VALIDX_MAX_REQUEST_BYTES`
- `VALIDX_MAX_SUBPROCESS_IO_BYTES`
- `VALIDX_MAX_SCHEMA_CACHE_SIZE`
- `VALIDX_SUBPROCESS_TIMEOUT_MS`
- `VALIDX_SUBPROCESS_MAX_RETRIES`
- `VALIDX_SUBPROCESS_BACKOFF_MS`

## Rollback

```bash
pip install valid8x==<previous-version>
```

PyPI retains every published version. See `SUPPORT.md` for details.
