valid8x 0.6.0

Valid8X — JSON Schema 2020-12 validator that emits a signed, replayable evidence receipt (canonical payload + SBOM + HMAC-signed provenance token) for every run.

Valid8X

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

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

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

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:

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 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

pip install valid8x==<previous-version>

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