schema(v4): P0-2 — strict v4 GA JSON schemas (coexist with preview, docs+schema only)#42
Merged
Merged
Conversation
…preview)
Ships the GA strict equivalents of klickd-v4-preview.schema.json /
klickd-payload-v4-preview.schema.json:
- schema/klickd-v4.schema.json (unified)
- schemas/klickd-payload-v4.schema.json (split — payload)
Strict on the v4 surface frozen by Accepted RFCs:
- RFC-001 v1 media_profile (version + entries[], BLAKE3 hash, closed
modality enum), with a permissive "summary" branch retained for
round-trip parity with vectors_v40_preview.json
- RFC-002 v1 core verification_gates (five-level enum, structured + flat
forms), human_veto_policy (incl. min_level), claim_sources v1
- RFC-004 v1 frozen migration fields
Permissive on Draft surface (reversibility, blast_radius, contract_tests,
success_criteria, verification_artifacts, error_journal.rule_created,
risk_thresholds, preflight_checks, context_cost) so a future strict bump
can tighten them without breaking GA writers.
Envelope contract retained from v3 (Argon2id + AES-256-GCM, §33.10 #2):
encrypted=true requires kdf + cipher + ciphertext via if/then.
Top-level additionalProperties: true is preserved on both schemas to
honor the SPEC.md §33.7 unknown-field preservation invariant.
Coexistence: the preview schemas remain in place unchanged and remain
authoritative for preview files. payload_schema_version accepts both
"4.0" (GA) and "4.0.0-preview.1" so the 5 personas and every
expected_payload of tests/vectors_v40_preview.json validate against
the strict payload schema.
Tooling:
- scripts/validate_v4_schemas.py — local validator (positive +
5 negative cases), exit 1 on failure.
Docs:
- SCHEMA_INDEX.md, schema/README.md, schemas/README.md — list the
GA strict files and the coexistence rules.
- docs/roadmap/ROAD-TO-V4-GA.md §P0-2 — status note; P0-6 strict
vectors remain pending before the full DoD is ticked.
- examples/v4/personas/README.md — DoD checkbox for strict
validation flipped, P0-6 vectors checkbox kept open.
Governance: no SDK bump, no new vectors, no Git tag, no npm/PyPI/Zenodo
release. Existing verify_vectors.py suite (59/59) still passes — no
regression on v2.5, v3.0, adversarial, or v4.0-preview tracks.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
11 tasks
Davincc77
added a commit
that referenced
this pull request
May 24, 2026
…ma (#43) * sdk(python,v4): P0-3 — align klickd Python SDK with v4 GA strict schema Adds a v4 schema validation surface to the Python SDK (P0-3) without bumping the package version (`4.0.0a1`) and without touching the v3 envelope crypto contract (SPEC.md §33.10 #2 frozen). What ships: - `klickd.validate(payload, strict=True|False, target="payload"|"unified")` with the strict GA candidate (P0-2) and permissive v4 preview schemas bundled as package data under `klickd/schemas/`. - `klickd.validate_iter_errors(...)` non-raising variant for wizards (R4-P0-1 reload-verification surface area). - Optional `[validate]` extra (`pip install klickd[validate]`) — `jsonschema` stays optional so callers who only need load/save are unaffected. - v4 TypedDicts: `KlickdMediaProfileV1`, `KlickdVerificationGatesV1`, `KlickdGateEntry`, `KlickdHumanVetoPolicy`, `KlickdClaimSources`, `KlickdMigrationV1` (additive to `KlickdPayload`). - README block documenting the new surface + the §33.7 verbatim round-trip guarantee on v4 additive fields. What does NOT ship: - No envelope/version bump, no PyPI publish, no Git tag, no Zenodo DOI — Phase B governance reminder respected. - No SDK alignment of the docs-only R4-P0-2 codes (`KLICKD_E_PASS_MISMATCH`, `KLICKD_E_SAVE_LOCAL`, `KLICKD_E_LEGACY_VERSION`, `KLICKD_E_CORRUPT`, `KLICKD_E_POLICY_LOCKED`, `KLICKD_E_UNSAFE_QR`); R4-P0-2 §4 explicitly defers SDK exposure to a later track. Tests (63 / 63 pass): - 5 R4-P0-3 personas validate against strict payload + unified + preview. - 5 personas round-trip verbatim (single + double round-trip). - Negative cases: unknown gate level, missing media hash, unknown modality, unsupported `payload_schema_version`, encrypted envelope missing kdf/cipher/ciphertext. - Both structured + flat `verification_gates` shapes accepted. - Preview value `"4.0.0-preview.1"` accepted by strict schema (P0-2 design — preview-era files round-trip without rewrite). - v3.x payloads unaffected (no regression). - Unknown top-level fields validate AND round-trip verbatim. - `tests/test_v4_preview_roundtrip.py` and `tests/test_roundtrip.py` unchanged and still green. Repo-level checks: `scripts/validate_v4_schemas.py` ✓ ; `verify_vectors.py` 59/59 ✓ ; JS `verify_vectors.mjs` 29/29 ✓ . Refs: P0-3 in `docs/roadmap/ROAD-TO-V4-GA.md`, depends on P0-1 + P0-2 (merged in #42). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * ci(python,v4): install klickd[validate] extra so v4 strict tests run The new tests/test_v4_ga_strict.py suite uses klickd.validate, which is gated on the optional jsonschema dependency. The CI step now installs the [validate] extra so the strict-schema tests execute; the test file also pytest.importorskip()s on jsonschema so a local run without the extra cleanly skips the validation tests instead of erroring. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Code <claude-code@anthropic.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
ROAD-TO-V4-GA.md§P0-2:schema/klickd-v4.schema.json(unified)schemas/klickd-payload-v4.schema.json(split — payload)klickd-v4-preview.schema.json/klickd-payload-v4-preview.schema.json— preview schemas are unchanged and remain authoritative for preview files.What's strict, what's not
Strict (sections frozen by Accepted RFCs):
media_profile—version: 1,entries[], closed modality enum (voice·image·document·embedding), BLAKE3 hash mandatory.verification_gates(five-level enum, structured + flat forms both accepted),human_veto_policy(incl.min_level),claim_sourcesv1 (prefer,require_citation_for).migrationfields.encrypted: true⇒kdf+cipher+ciphertextrequired viaif/then.Permissive (sections still
Draft):reversibility,blast_radius,contract_tests,success_criteria,verification_artifacts,error_journal[].rule_created.risk_thresholds,preflight_checks,context_cost,gaming_profile.payload_schema_versionenum accepts both"4.0"(GA) and"4.0.0-preview.1"for round-trip parity.Preserved: top-level
additionalProperties: trueon both schemas — SPEC.md §33.7 unknown-field preservation is unconditional.Test plan
python3 scripts/validate_v4_schemas.py— all 5 persona examples +examples/v4-preview/minimal.klickd+ 7expected_payloadentries fromtests/vectors_v40_preview.jsonvalidate against strict schemas; 5 negative cases each fail as expected.python3 verify_vectors.py— 59/59 existing vectors pass (v2.5, v3.0, adversarial, v4.0-preview). Zero regression.test-vectorsworkflow continues to run unchanged. Strict-schema validator is local-only in this PR (CI wiring deferred to keep the PR focused).Impacts on next P0 tracks
klickd4.0.0) and P0-4 (SDK TS@klickd/core4.0.0) can now load these two schemas as the strict validation entry points. Recommended SDK surface:validate(payload, strict=True)cross-referencesschemas/klickd-payload-v4.schema.jsonwhilestrict=Falsekeeps the preview schema. The schema choice of accepting both"4.0"and"4.0.0-preview.1"inpayload_schema_versionwas made specifically so SDKs can default to the strict schema for both populations.scripts/validate_v4_schemas.py) is the obvious place to hook them. The R4-P0-3 persona README explicitly notes P0-6 is still pending.Governance reminder
This PR is docs + schema only. No code under
packages/is touched. No version bump. No tag. Do not merge without Vince's explicit sign-off, even though the previous Phase A PRs were merged on the same governance terms.🤖 Generated with Claude Code