valid8x 0.4.2

ValidX: deterministic JSON Schema 2020-12 validator with governed repair/explain hooks.

ValidX v0.4.2

Deterministic JSON Schema 2020-12 validation + governed repair loop with evidence artifacts (verify_report.json, payload.canon.json, errors.json).

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

• validx_v1_scaffold_bundle_v0_4_1.zip
• validx_v1_scaffold_bundle_v0_4_1.zip.sha256

Build locally with:

python3 scripts/package_bundle.py --out validx_v1_scaffold_bundle_v0_4_1.zip
sha256sum validx_v1_scaffold_bundle_v0_4_1.zip > validx_v1_scaffold_bundle_v0_4_1.zip.sha256

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