@klickd/core 3.5.1 → 4.0.0

package/dist/klickd-payload-v4.schema-7UPTEJOY.json

@@ -0,0 +1,354 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://klickd.app/schemas/v4/klickd-payload.schema.json",
+  "title": "klickd Payload v4 (Strict GA candidate, normative)",
+  "description": "Strict JSON Schema for the .klickd v4 inner payload. This schema is the GA strict equivalent of the permissive klickd-payload-v4-preview.schema.json. Strict blocks correspond to RFC-001 (media_profile v1, Accepted) and RFC-002 v1 core (verification_gates, human_veto_policy, claim_sources v1, Accepted). Sections that remain Draft (RFC-002 v2-additive: contract_tests, success_criteria, reversibility, blast_radius, verification_artifacts, error_journal.rule_created; RFC-004 migration runtime) are accepted but left permissive so they can be tightened by a future strict schema bump without breaking GA writers. Top-level additionalProperties is TRUE to preserve unknown fields verbatim (SPEC.md §33.7 forward-compatibility invariant). Strict shape on frozen sub-objects uses additionalProperties: false locally. Does NOT supersede the permissive preview schema (klickd-payload-v4-preview.schema.json) — both coexist until the preview sunset announced separately.",
+  "type": "object",
+  "required": [
+    "payload_schema_version"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "payload_schema_version": {
+      "type": "string",
+      "description": "Payload schema version. For GA strict files, the canonical value is '4.0'. The preview value '4.0.0-preview.1' is also accepted so a preview file already in the wild round-trips against the strict schema without forcing a rewrite. A future strict bump (4.1, etc.) MAY tighten this enum.",
+      "enum": ["4.0", "4.0.0-preview.1"]
+    },
+    "domain_schema_version": {
+      "type": "string",
+      "description": "Domain-specific schema version. Two accepted forms: (a) v3-style '{domain}-{major}.{minor}' (e.g. 'education-1.2'); (b) bare semver-ish '{major}.{minor}(.{patch})?' for domain-agnostic profiles (e.g. '1.0.0').",
+      "pattern": "^([a-z][a-z0-9_-]*-\\d+\\.\\d+|\\d+\\.\\d+(\\.\\d+)?)$"
+    },
+    "preview": {
+      "type": "string",
+      "description": "OPTIONAL preview marker. Present only on files written against a preview iteration (e.g. 'v4.0.0-preview.1'). Absent on GA strict files."
+    },
+    "profile_kind": {
+      "type": "string",
+      "description": "Top-level discriminator for the profile shape. Reserved canonical values: 'learner', 'agent', 'team', 'robot', 'creator'. Custom strings are permitted (extension space). v3.x is implicitly 'learner'."
+    },
+    "injection_target": {
+      "type": "string",
+      "enum": ["system_prompt", "user_message", "both"],
+      "description": "Where to inject the .klickd context (carried over from v3.x §20.2)."
+    },
+    "identity": {
+      "type": "object",
+      "description": "Persistent user identity attributes. Carried over from v3 SPEC §8; same strictness as v3 payload schema. All sub-fields are OPTIONAL.",
+      "additionalProperties": true,
+      "properties": {
+        "name": {"type": "string", "maxLength": 256},
+        "display_name": {"type": "string", "maxLength": 256, "description": "v4 GA preferred user-facing alias. Either 'name' or 'display_name' may be used; producers SHOULD pick one."},
+        "language": {"type": "string", "description": "BCP 47 language tag."},
+        "timezone": {"type": "string", "description": "IANA time zone identifier."},
+        "communication_style": {"type": "string"}
+      }
+    },
+    "companion_identity": {
+      "type": "object",
+      "description": "Optional companion / co-agent persona. Same surface as v3.4 §27. Permissive.",
+      "additionalProperties": true
+    },
+    "context": {
+      "type": "object",
+      "description": "Operational session state. Carried over from v3 SPEC §9. Permissive (unevaluatedProperties policy of v3 retained).",
+      "additionalProperties": true
+    },
+    "knowledge": {
+      "type": "object",
+      "description": "Structured knowledge state. Carried over from v3 SPEC §10. Permissive.",
+      "additionalProperties": true
+    },
+    "memory": {
+      "type": "array",
+      "maxItems": 1000,
+      "description": "Structured conversation/event log. Same v3 §11 constraints retained.",
+      "items": {"type": "object", "additionalProperties": true}
+    },
+    "learning_goal": {
+      "type": "object",
+      "description": "User's stated learning / delivery goal. Same surface as v3 §27. Permissive.",
+      "additionalProperties": true,
+      "properties": {
+        "type": {"type": "string"},
+        "deadline": {"type": "string"},
+        "stakes": {"type": "string", "enum": ["low", "medium", "high"]}
+      }
+    },
+    "user_preferences": {
+      "oneOf": [
+        {"type": "string", "maxLength": 32768},
+        {"type": "object", "additionalProperties": true}
+      ],
+      "description": "Canonical type is string (v3.5 §22.6). Object form retained for backward compatibility."
+    },
+    "agent_instructions": {
+      "type": "string",
+      "maxLength": 32768,
+      "description": "System-prompt injection string. Same v3 §7.2 contract."
+    },
+    "onboarding_trigger": {
+      "type": "string",
+      "description": "Optional onboarding trigger (v3.4 §29b). Common values: 'on_new_agent', 'manual'."
+    },
+    "ethics": {
+      "type": "object",
+      "description": "Ethical guard surface (v3.x). Permissive in this schema; safety / locked fields are governed by docs/spec/DEPRECATION_POLICY_V4.md §9.",
+      "additionalProperties": true
+    },
+    "media_profile": {
+      "description": "RFC-001 v1 (Accepted): portable, hash-referenced media context. Strict on the v1 frozen surface (versioned + entries[]); a permissive 'summary' form (preview-era) is also accepted for round-trip compatibility. New modalities / fields land via additive RFC bumps.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["version", "entries"],
+          "properties": {
+            "version": {"type": "integer", "const": 1, "description": "media_profile schema version. v1 per RFC-001."},
+            "entries": {
+              "type": "array",
+              "maxItems": 256,
+              "items": {"$ref": "#/$defs/mediaProfileEntry"}
+            }
+          }
+        },
+        {
+          "type": "object",
+          "description": "Permissive summary form (preview-era). Strict producers SHOULD migrate to the versioned + entries[] form. Kept for round-trip parity with vectors_v40_preview.json.",
+          "additionalProperties": true,
+          "not": {"required": ["version", "entries"]}
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "verification_gates": {
+      "description": "RFC-002 v1 core (Accepted): user's preferred friction profile per action class. Two accepted shapes: (a) structured form (recommended) with version + gates[]; (b) flat map {action_class: level} for compactness (used by §33.5 minimal example and preview readers).",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["version", "gates"],
+          "properties": {
+            "version": {"type": "integer", "const": 1},
+            "user_default": {"$ref": "#/$defs/gateLevel"},
+            "gates": {
+              "type": "array",
+              "maxItems": 256,
+              "items": {"$ref": "#/$defs/gateEntry"}
+            }
+          }
+        },
+        {
+          "type": "object",
+          "description": "Flat map form: {action_class: gate_level}. Each value MUST be one of the five canonical levels.",
+          "additionalProperties": {"$ref": "#/$defs/gateLevel"}
+        }
+      ]
+    },
+    "human_veto_policy": {
+      "description": "RFC-002 v1 (Accepted): standing rules about when a human MUST be in the loop. Overrides any lower gate.",
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "applies_to": {
+          "type": "array",
+          "items": {"type": "string"},
+          "maxItems": 64,
+          "description": "List of action classes for which a human veto is required."
+        },
+        "second_party": {
+          "type": ["string", "null"],
+          "description": "Optional named second party who may unlock. null means owner-only."
+        },
+        "min_level": {
+          "$ref": "#/$defs/gateLevel",
+          "description": "Floor gate level. The policy MUST NOT resolve below this level for any action class in 'applies_to'. RFC-002 v1 §4 #6 — human veto is sacred."
+        },
+        "rationale": {"type": "string", "maxLength": 1024}
+      }
+    },
+    "claim_sources": {
+      "description": "RFC-002 v1 (Accepted) + v2-additive (Draft). Strict on v1 fields ('prefer', 'require_citation_for'); 'records' and extended fields remain permissive (v2 still Draft).",
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "properties": {
+        "prefer": {
+          "type": "array",
+          "items": {"type": "string"},
+          "maxItems": 64,
+          "description": "Ordered preference list. Each entry is a free-form source identifier; common values: 'user_supplied', 'tool:web_search', 'tool:doi_resolver'."
+        },
+        "require_citation_for": {
+          "type": "array",
+          "items": {"type": "string"},
+          "maxItems": 64
+        },
+        "records": {
+          "type": "array",
+          "description": "v2-additive (Draft). Permissive until promoted.",
+          "items": {"type": "object", "additionalProperties": true}
+        }
+      }
+    },
+    "risk_thresholds": {
+      "description": "RFC-002 v1 (Accepted): numeric / categorical knobs. Permissive on inner shape — extension space.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "preflight_checks": {
+      "description": "RFC-002 v1 (Accepted): small named checks to run before acting. Each entry is an object with at minimum 'name'.",
+      "type": ["array", "null"],
+      "items": {"type": ["object", "string"], "additionalProperties": true}
+    },
+    "error_journal": {
+      "description": "RFC-002 v1 (Accepted): append-only lessons learned. Permissive on entry shape ('rule_created' remains Draft in v2-additive).",
+      "type": ["array", "null"],
+      "items": {"type": "object", "additionalProperties": true}
+    },
+    "verification_artifacts": {
+      "description": "RFC-002 §8b.8 (Draft, v2-additive). Permissive: pointer ledger, not a payload sink. Accepted as null or array.",
+      "type": ["array", "null"],
+      "items": {"type": "object", "additionalProperties": true}
+    },
+    "contract_tests": {
+      "description": "RFC-002 v2-additive (Draft). Permissive.",
+      "type": ["array", "null"],
+      "items": {"type": "object", "additionalProperties": true}
+    },
+    "success_criteria": {
+      "description": "RFC-002 v2-additive (Draft). Permissive.",
+      "type": ["object", "array", "null"],
+      "additionalProperties": true
+    },
+    "reversibility": {
+      "description": "RFC-002 v2-additive (Draft). Permissive — typical shape is {action_class: enum<reversible|costly_to_reverse|irreversible|low|none|high>} but enums are not yet frozen.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "blast_radius": {
+      "description": "RFC-002 v2-additive (Draft). Permissive.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "migration": {
+      "description": "RFC-004 (Draft): optional migration metadata block. Audit-only — no migration tooling ships with the strict schema. Strict on v1 frozen fields; extension fields permitted.",
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "properties": {
+        "source_version": {"type": "string"},
+        "migrated_at": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
+        },
+        "migration_report_ref": {"type": "string"},
+        "backup_ref": {"type": "string"}
+      }
+    },
+    "context_cost": {
+      "description": "Research/benchmark track (benchmarks/context_cost/RFC.md). No spec semantics depend on this field. Permissive.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "gaming_profile": {
+      "description": "R4-P1-4 gaming.klickd baseline (preview, registry-based). NOT a v4 MUST. Accepted as a registry-defined optional profile; permissive structure.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "deprecated_fields": {
+      "description": "OPTIONAL informational block defined by docs/spec/DEPRECATION_POLICY_V4.md §6. Lists fields the producer has emitted as 'deprecated' status. Readers that don't understand it MUST silently ignore (§33.7).",
+      "type": ["array", "null"],
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["name"],
+        "properties": {
+          "name": {"type": "string"},
+          "since": {"type": "string"},
+          "replacement": {"type": ["string", "null"]},
+          "removal_target": {"type": ["string", "null"]}
+        }
+      }
+    },
+    "_example_metadata": {
+      "description": "Optional non-normative block used by repository examples (see examples/v4/personas/README.md). Carries 'persona', 'non_normative', 'contains_real_pii', 'contains_secrets', etc. A reader MUST NOT use this block as a trust signal.",
+      "type": "object",
+      "additionalProperties": true
+    }
+  },
+  "$defs": {
+    "gateLevel": {
+      "type": "string",
+      "enum": ["silent", "warn", "confirm", "block", "require-owner"],
+      "description": "RFC-002 v1 §6 — fixed enum of five gate levels. No new levels are added in GA."
+    },
+    "gateEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action_class", "level"],
+      "properties": {
+        "id": {"type": "string", "maxLength": 128},
+        "action_class": {"type": "string", "maxLength": 128},
+        "level": {"$ref": "#/$defs/gateLevel"},
+        "reason": {"type": "string", "maxLength": 1024}
+      }
+    },
+    "mediaProfileEntry": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["id", "modality", "hash"],
+      "description": "RFC-001 v1 entry. Strict on v1 frozen fields (id, modality, hash). Additional metadata (consent, producer, etc.) is permitted as extension surface.",
+      "properties": {
+        "id": {"type": "string", "maxLength": 128},
+        "modality": {
+          "type": "string",
+          "enum": ["voice", "image", "document", "embedding"],
+          "description": "RFC-001 v1 §4 #3 — closed enum at v1. Custom modalities live under 'x_*' namespaces (outside this entry)."
+        },
+        "label": {"type": "string", "maxLength": 256},
+        "language": {"type": "string"},
+        "uri": {"type": "string", "description": "May be file://, https://, ipfs://, cas://<hash>, or a relative path. Reader chooses how to resolve."},
+        "media_type": {"type": "string"},
+        "byte_size": {"type": "integer", "minimum": 0},
+        "duration_ms": {"type": "integer", "minimum": 0},
+        "bytes_b64": {
+          "type": "string",
+          "contentEncoding": "base64",
+          "description": "Inline base64 PERMITTED ONLY for entries ≤ 16 KiB total (RFC-001 v1 §4 #1). Strict enforcement of the 16 KiB cap is not expressible in JSON Schema and is enforced by reader-side logic."
+        },
+        "hash": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["algo", "value"],
+          "properties": {
+            "algo": {"type": "string", "const": "blake3", "description": "RFC-001 v1 §4 #2 — one hash, one algorithm: BLAKE3."},
+            "value": {"type": "string", "description": "Hash value, encoding per RFC-001 (base64 or hex-prefixed). Strict format enforcement is reader-side."}
+          }
+        },
+        "producer": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "kind": {"type": "string"},
+            "device": {"type": "string"}
+          }
+        },
+        "consent": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "RFC-001 v1 §4 #5 — consent is per-entry, not per-file.",
+          "properties": {
+            "purposes": {
+              "type": "array",
+              "items": {"type": "string"},
+              "maxItems": 64
+            },
+            "expires_at": {"type": "string"},
+            "revocable": {"type": "boolean"}
+          }
+        }
+      }
+    }
+  }
+}

package/dist/klickd-v4-preview.schema-QHITWMK6.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://klickd.app/schema/v4-preview/klickd.schema.json",
+  "title": "klickd v4 Preview — Unified (PERMISSIVE, NON-NORMATIVE)",
+  "description": "PREVIEW unified schema for .klickd v4, targeting v4.0.0-preview.1. This schema is INTENTIONALLY PERMISSIVE: it validates the top-level shape of a v4-preview file (envelope + optional preview hooks) without enforcing strict v4 semantics. additionalProperties is true so unknown fields round-trip verbatim. Use this for single-pass acceptance of draft v4 documents. For pre-/post-decrypt validation, see schemas/klickd-payload-v4-preview.schema.json. The normative production schemas remain schema/klickd-v3.4.schema.json (unified) and schemas/klickd-envelope-v3.schema.json + schemas/klickd-payload-v3.schema.json (split). See SPEC.md §33.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["klickd_version", "created_at", "encrypted"],
+  "properties": {
+    "klickd_version": {
+      "type": "string",
+      "description": "Wire / envelope version. PERMISSIVE in this preview — any MAJOR.MINOR string is accepted. Preview producers SHOULD emit '4.0' and pair it with a 'preview' field. v3.x producers MUST continue to emit '3.x' and MUST NOT emit a 'preview' field.",
+      "pattern": "^\\d+\\.\\d+(\\.[0-9A-Za-z-.]+)?$"
+    },
+    "preview": {
+      "type": "string",
+      "description": "Marks a file as belonging to a specific preview iteration. Recommended value for files written against this schema: 'v4.0.0-preview.1'. Absent in v3.x and in a future GA v4.0."
+    },
+    "created_at": {
+      "type": "string",
+      "description": "RFC 3339 UTC timestamp of file creation. Same contract as v3.x.",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "format": "date-time"
+    },
+    "encrypted": {
+      "type": "boolean",
+      "description": "Whether the payload is AES-256-GCM encrypted. Envelope cryptography is unchanged from v3.x in this preview."
+    },
+    "domain": {
+      "type": "string",
+      "description": "Semantic category of the context. Same surface as v3.x; custom strings remain permitted."
+    },
+    "profile_kind": {
+      "type": "string",
+      "description": "Top-level discriminator for the profile shape. Common values: 'learner', 'agent', 'team', 'robot'. Custom strings are permitted."
+    },
+    "ciphertext": {
+      "type": "string",
+      "description": "AES-256-GCM ciphertext when encrypted is true. Same contract as v3.x.",
+      "contentEncoding": "base64"
+    },
+    "iv": {
+      "type": "string",
+      "contentEncoding": "base64"
+    },
+    "kdf_salt": {
+      "type": "string",
+      "contentEncoding": "base64"
+    },
+    "kdf": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Structured KDF block as in envelope-v3. Unchanged in this preview."
+    },
+    "cipher": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Structured cipher block as in envelope-v3. Unchanged in this preview."
+    },
+    "media_profile": {
+      "description": "RFC-001 (preview hook). PERMISSIVE — see schemas/klickd-payload-v4-preview.schema.json.",
+      "type": ["object", "array", "null"],
+      "additionalProperties": true
+    },
+    "verification_gates": {
+      "description": "RFC-002 (preview hook). PERMISSIVE.",
+      "type": ["object", "array", "null"],
+      "additionalProperties": true
+    },
+    "human_veto_policy": {
+      "description": "RFC-002 (preview hook). PERMISSIVE.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "claim_sources": {
+      "description": "RFC-002 (preview hook). PERMISSIVE.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "verification_artifacts": {
+      "description": "RFC-002 §8b.8 (preview hook). PERMISSIVE — pointer ledger, not a payload sink.",
+      "type": ["array", "null"]
+    },
+    "migration": {
+      "description": "RFC-004 (preview hook). Audit-only in v4.0.0-preview.1.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "context_cost": {
+      "description": "Research/benchmark track (preview hook). No normative semantics.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    }
+  }
+}

package/dist/klickd-v4.schema-ZZGRYTLY.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://klickd.app/schema/v4/klickd.schema.json",
+  "title": "klickd v4 — Unified (Strict GA candidate, normative)",
+  "description": "Strict unified JSON Schema for a .klickd v4 document (envelope + optional inline payload). This schema is the GA strict equivalent of the permissive klickd-v4-preview.schema.json. It validates the envelope shape strictly (mirroring the v3 envelope contract — Argon2id + AES-256-GCM is unchanged in v4 per SPEC.md §33.10 #2) and, for unencrypted files, validates the inline payload against the strict v4 payload schema (klickd-payload-v4.schema.json). Top-level additionalProperties is TRUE to preserve unknown fields verbatim (SPEC.md §33.7 forward-compatibility invariant). Does NOT supersede the permissive preview schema (klickd-v4-preview.schema.json) — both coexist.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["klickd_version", "created_at", "encrypted"],
+  "properties": {
+    "klickd_version": {
+      "type": "string",
+      "description": "Wire / envelope version. Strict v4 GA producers SHOULD emit '4.0'. v3.x values are also accepted because the v3 envelope contract is unchanged (§33.10 #2) and a v3.x file remains readable by a v4 reader.",
+      "pattern": "^(3|4)\\.\\d+(\\.[0-9A-Za-z-.]+)?$"
+    },
+    "preview": {
+      "type": "string",
+      "description": "OPTIONAL preview marker. Absent on GA strict files. If present, this file was written against a preview iteration (e.g. 'v4.0.0-preview.1')."
+    },
+    "created_at": {
+      "type": "string",
+      "description": "RFC 3339 UTC timestamp of file creation. Z-suffix only, no fractional seconds (matches v3 envelope strict contract).",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    "encrypted": {
+      "type": "boolean"
+    },
+    "domain": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Semantic category. Registered values follow v3 (education, work, finance, legal, creative, health, research, robotics, gaming, creator). Custom non-empty strings are permitted."
+    },
+    "profile_kind": {
+      "type": "string",
+      "description": "Top-level discriminator for the profile shape. Reserved canonical values: 'learner', 'agent', 'team', 'robot', 'creator'."
+    },
+    "domain_schema_version": {
+      "type": "string",
+      "pattern": "^([a-z][a-z0-9_-]*-\\d+\\.\\d+|\\d+\\.\\d+(\\.\\d+)?)$"
+    },
+    "kdf": {
+      "type": "object",
+      "description": "Structured KDF block — same contract as envelope-v3 §15.",
+      "required": ["name", "params", "salt"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string", "enum": ["argon2id", "pbkdf2-sha256"]},
+        "params": {
+          "oneOf": [
+            {
+              "type": "object",
+              "required": ["m", "t", "p"],
+              "additionalProperties": false,
+              "properties": {
+                "m": {"type": "integer", "minimum": 65536},
+                "t": {"type": "integer", "minimum": 1},
+                "p": {"type": "integer", "minimum": 1}
+              }
+            },
+            {
+              "type": "object",
+              "required": ["iterations"],
+              "additionalProperties": false,
+              "properties": {
+                "iterations": {"type": "integer", "minimum": 600000}
+              }
+            }
+          ]
+        },
+        "salt": {"type": "string"}
+      }
+    },
+    "cipher": {
+      "type": "object",
+      "description": "Structured cipher block — same contract as envelope-v3 §16. v4 does not introduce a new cipher.",
+      "required": ["name", "iv"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string", "const": "AES-256-GCM"},
+        "iv": {"type": "string"}
+      }
+    },
+    "ciphertext": {
+      "type": "string",
+      "description": "AES-256-GCM ciphertext (base64 padded). Required when encrypted=true."
+    },
+    "iv": {
+      "type": "string",
+      "description": "Legacy top-level IV mirror, retained for v3.0 round-trip parity. New producers SHOULD place IV inside the structured cipher block."
+    },
+    "kdf_salt": {
+      "type": "string",
+      "description": "Legacy top-level salt mirror, retained for v3.0 round-trip parity."
+    },
+    "payload_schema_version": {
+      "type": "string",
+      "description": "Payload schema version when the payload is inline (encrypted=false). Strict v4 GA value: '4.0'. Preview '4.0.0-preview.1' accepted for round-trip.",
+      "enum": ["4.0", "4.0.0-preview.1"]
+    },
+    "media_profile": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/media_profile"},
+    "verification_gates": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/verification_gates"},
+    "human_veto_policy": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/human_veto_policy"},
+    "claim_sources": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/claim_sources"},
+    "verification_artifacts": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/verification_artifacts"},
+    "contract_tests": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/contract_tests"},
+    "success_criteria": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/success_criteria"},
+    "reversibility": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/reversibility"},
+    "blast_radius": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/blast_radius"},
+    "risk_thresholds": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/risk_thresholds"},
+    "preflight_checks": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/preflight_checks"},
+    "error_journal": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/error_journal"},
+    "migration": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/migration"},
+    "context_cost": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/context_cost"},
+    "gaming_profile": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/gaming_profile"},
+    "deprecated_fields": {"$ref": "https://klickd.app/schemas/v4/klickd-payload.schema.json#/properties/deprecated_fields"}
+  },
+  "allOf": [
+    {
+      "if": {
+        "type": "object",
+        "properties": {"encrypted": {"const": true}},
+        "required": ["encrypted"]
+      },
+      "then": {
+        "required": ["kdf", "cipher", "ciphertext"],
+        "description": "Encrypted v4 file MUST carry kdf + cipher + ciphertext (envelope-v3 contract retained)."
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klickd/core",
-  "version": "3.5.1",
+  "version": "4.0.0",
   "description": "Official JavaScript/TypeScript library for reading and writing .klickd portable AI context files",
   "keywords": [
     "klickd",
@@ -9,13 +9,13 @@
     "memory",
     "encrypted"
   ],
-  "homepage": "https://klickd.app",
+  "homepage": "https://klickd.app/klickdskill",
   "repository": {
     "type": "git",
     "url": "https://github.com/Davincc77/klickdskill"
   },
   "license": "CC0-1.0",
-  "author": "Vince C. <Luxlearn@pm.me> (https://klickd.app)",
+  "author": "Vincenzo Cirilli (.klickd) <hello@klickd.app> (https://klickd.app)",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -33,7 +33,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --external argon2 --external argon2-browser",
+    "build": "tsup src/index.ts --format esm,cjs --dts --external argon2 --external argon2-browser --external ajv --loader .json=copy",
     "test": "node --experimental-vm-modules node_modules/.bin/jest",
     "prepublishOnly": "npm run build"
   },
@@ -41,9 +41,18 @@
     "canonicalize": "^2.0.0",
     "hash-wasm": "^4.11.0"
   },
+  "peerDependencies": {
+    "ajv": "^8.12.0"
+  },
+  "peerDependenciesMeta": {
+    "ajv": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/jest": "^29.0.0",
     "@types/node": "^20.0.0",
+    "ajv": "^8.12.0",
     "argon2": "^0.44.0",
     "argon2-browser": "^1.18.0",
     "jest": "^29.0.0",