Skip to content

v4.0.0-preview.1 (preview, NOT GA)

Pre-release
Pre-release

Choose a tag to compare

View all tags
@Davincc77 Davincc77 released this 23 May 07:47
v4.0.0-preview.1
c4282ed
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

.klickd v4.0.0-preview.1 — Release Notes

Status: PREVIEW / NON-NORMATIVE / NOT GA.
This is a preview release intended for early implementers. The stable,
recommended production format remains v3.5.1.

Distribution mapping for this preview:

  • git tag: v4.0.0-preview.1 (GitHub Release marked Pre-release)
  • npm: @klickd/core@4.0.0-preview.1 published under the preview dist-tag (not latest)
  • PyPI: klickd==4.0.0a1 (PEP 440 pre-release; pip install klickd continues to resolve to 3.5.1)
  • Zenodo: deferred — no DOI minted for the preview pending field-by-field validation

TL;DR

v4.0.0-preview.1 is the first preview milestone of the .klickd v4 track. It
is additive over v3.5.1: the wire envelope, crypto, and AAD construction
are unchanged (klickd_version stays at "3.0"); only the inner payload may
opt in to v4 preview fields via payload_schema_version = "4.0.0-preview.1".

The goal of this preview is to expose the v4 payload surface (verification
gates, media profile, migration reporting, context-cost telemetry) to early
implementers and gather feedback before any GA decision is made.

Production users should continue to use v3.5.1.

What's in the preview

1. Specification — SPEC §33 (non-normative)

A new section in SPEC.md describes the v4 preview track:

  • preview payload fields,
  • the unknown-field preservation rule (must_preserve_fields),
  • dual-reader contract (v3.x readers MUST ignore preview fields; v4-preview
    readers MUST round-trip them),
  • preview deprecation / sunset policy.

2. Permissive schemas

  • schemas/klickd-payload-v4-preview.schema.json
  • schema/klickd-v4-preview.schema.json

JSON Schema Draft 2020-12, deliberately permissive
(additionalProperties: true), no strict business validation.

3. SDK round-trip preservation (additive)

Both reference SDKs preserve unknown / preview fields verbatim:

  • Python: packages/pypi/klickd
  • TypeScript: packages/@klickd/core

No new public API surface for v4 validation. No migration helpers. Preview
fields are opaque to the libraries — they round-trip, nothing more.

4. Test vectors and cross-implementation verifiers

  • tests/vectors_v40_preview.json — 7 positive vectors (minimal payload,
    media_profile, verification_gates, claim_sources +
    verification_artifacts, migration report, context_cost, unknown-field
    passthrough).
  • Byte-stable regeneration via scripts/generate_v40_preview_vectors.py
    (fixed salts / IVs).
  • verify_vectors.py and verify_vectors.mjs each gain a v4 preview suite
    asserting decrypt success, payload_schema_version match, and deep-equality
    of must_preserve_fields. v2.5 / v3.0 / negative / adversarial suites are
    unchanged.

5. Benchmarks — Context Cost (RFC-003)

  • benchmarks/context_cost/ — fixtures-only scaffold with a local dry-run
    runner. No provider calls, no network, no API keys. Produces deterministic
    local artefacts.
  • Optional edge-case fixtures: migration, tool-failure, multi-session.
  • Provider scoring is not yet wired up.

6. Integrations — Hermes Agent POC

  • integrations/hermes/ — experimental POC scaffold. Local dry-run only;
    not a production integration. Useful as a reference for how .klickd can
    serve as portable state for an external workflow runner.

7. Design documents (drafts, non-normative)

All under docs/rfcs/:

  • RFC-001 — media_profile (v4-preview surface).
  • RFC-002 — verification_gates + human_veto, plus verification_artifacts
    / artifact-tee rule.
  • RFC-003 — Context Cost Benchmark (fixtures + dry-run runner).
  • RFC-004 — Migration & Backward Compatibility (docs-only).

These are explicitly non-normative until promoted by a future GA release.

Install

Stable (recommended for production)

pip install klickd          # v3.5.1
npm install @klickd/core    # v3.5.1

Preview (opt-in)

  • npm: npm install @klickd/core@4.0.0-preview.1 — published under the
    preview dist-tag, not latest. Default installs continue to resolve to
    v3.5.1.
  • PyPI: pip install klickd==4.0.0a1 (PEP 440 pre-release form;
    pip install klickd will continue to resolve to v3.5.1 because pre-releases
    are excluded by default).
  • PyPI authentication: uploads use the project's existing PyPI Trusted
    Publisher     workflow (.github/workflows/) — no long-lived API tokens.
  • Zenodo: deferred. No DOI has been minted for the preview; a
    preview-tagged deposit may be created in a follow-up after field-by-field
    validation. The concept DOI (10.5281/zenodo.20262530) is unchanged.

What stays unchanged

  • The stable, current production format remains v3.5.1.
  • The v3.5.1 published artefacts (npm @klickd/core, PyPI klickd, Zenodo
    DOI 10.5281/zenodo.20320480) are not modified.
  • v3.x readers MUST ignore preview fields; nothing in this preview changes the
    v3 wire format or crypto.

Known limitations

  • No strict v4 validator and no migration runner ship with the preview.
  • The Hermes integration is a POC scaffold — local dry-run only.
  • The Context Cost benchmark is fixtures-only; provider scoring is not yet
    wired up.
  • No GA timeline is committed. Field names, shapes, and semantics under SPEC
    §33 may change before GA without backwards-compatibility guarantees.

Upgrade / migration

There is no migration to perform. v3.5.1 files continue to load and validate
unchanged. Files that opt in to payload_schema_version = "4.0.0-preview.1"
will be ignored as opaque payload by v3.x consumers and preserved verbatim by
v4-preview-aware consumers.

References

Assets 2
Loading