@klickd/core 4.0.0-preview.1 → 4.0.0

package/README.md

@@ -2,13 +2,13 @@
 
 Official JavaScript/TypeScript library for reading and writing `.klickd` portable AI context files.
 
-**One soul. Any model. Any body.**
+**One soul. Any model. Any agent.** — open-source security and continuity layer for every actor in AI.
 
 Official page for the open `.klickd` format → **[klickd.app/klickdskill](https://klickd.app/klickdskill)**
 
 [![npm version](https://img.shields.io/npm/v/@klickd/core)](https://www.npmjs.com/package/@klickd/core)
 [![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://creativecommons.org/publicdomain/zero/1.0/)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20320480.svg)](https://doi.org/10.5281/zenodo.20320480)
+[![DOI (v4.0.0)](https://zenodo.org/badge/DOI/10.5281/zenodo.20383133.svg)](https://doi.org/10.5281/zenodo.20383133)
 
 ---
 
@@ -144,12 +144,12 @@ See `SPEC.md §33` and `examples/v4-preview/` for preview-track details.
 - Format page: [klickd.app/klickdskill](https://klickd.app/klickdskill)
 - Specification: [SPEC.md](https://github.com/Davincc77/klickdskill/blob/main/SPEC.md)
 - Repository: [github.com/Davincc77/klickdskill](https://github.com/Davincc77/klickdskill)
-- DOI: [10.5281/zenodo.20320480](https://doi.org/10.5281/zenodo.20320480) (v3.5) · concept DOI (all versions): [10.5281/zenodo.20262530](https://doi.org/10.5281/zenodo.20262530)
-- Homepage: [klickd.app](https://klickd.app)
+- DOI: [10.5281/zenodo.20383133](https://doi.org/10.5281/zenodo.20383133) (v4.0.0) · concept DOI (all versions): [10.5281/zenodo.20262530](https://doi.org/10.5281/zenodo.20262530)
+- Homepage: [klickd.app/klickdskill](https://klickd.app/klickdskill)
 
 ---
 
 ## License
 
 [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) — Public Domain Dedication.  
-Author: Vince C. (Luxlearn, Luxembourg)
+Author: Vincenzo Cirilli (.klickd / klickd.app, Luxembourg)

package/dist/index.cjs

@@ -32,8 +32,15 @@ var index_exports = {};
 __export(index_exports, {
   HTTP_STATUS: () => HTTP_STATUS,
   KlickdError: () => KlickdError,
+  getBundledSchema: () => getBundledSchema,
+  listBundledSchemas: () => listBundledSchemas,
   loadKlickd: () => loadKlickd,
-  saveKlickd: () => saveKlickd
+  migratePayload: () => migratePayload,
+  migratePayloadIterWarnings: () => migratePayloadIterWarnings,
+  needsMigration: () => needsMigration,
+  saveKlickd: () => saveKlickd,
+  validate: () => validate,
+  validateIterErrors: () => validateIterErrors
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -321,10 +328,265 @@ async function loadKlickd(input, options = {}) {
   }
   return payload;
 }
+
+// src/validate.ts
+var import_klickd_payload_v4_schema = __toESM(require("./klickd-payload-v4.schema-7UPTEJOY.json"), 1);
+var import_klickd_payload_v4_preview_schema = __toESM(require("./klickd-payload-v4-preview.schema-W7RY72VP.json"), 1);
+var import_klickd_v4_schema = __toESM(require("./klickd-v4.schema-ZZGRYTLY.json"), 1);
+var import_klickd_v4_preview_schema = __toESM(require("./klickd-v4-preview.schema-QHITWMK6.json"), 1);
+var SCHEMAS = {
+  "payload-strict": import_klickd_payload_v4_schema.default,
+  "payload-preview": import_klickd_payload_v4_preview_schema.default,
+  "unified-strict": import_klickd_v4_schema.default,
+  "unified-preview": import_klickd_v4_preview_schema.default
+};
+function getBundledSchema(key) {
+  const s = SCHEMAS[key];
+  if (!s) {
+    throw new Error(`Unknown schema key: ${String(key)}`);
+  }
+  return JSON.parse(JSON.stringify(s));
+}
+function listBundledSchemas() {
+  return Object.keys(SCHEMAS);
+}
+var ajvBundle = null;
+async function getAjv() {
+  if (ajvBundle) return ajvBundle;
+  let AjvCtor;
+  try {
+    const mod = await import("ajv/dist/2020.js");
+    AjvCtor = mod.default ?? mod;
+  } catch (e) {
+    throw new KlickdError(
+      "KLICKD_E_SCHEMA",
+      "validate() requires the optional 'ajv' dependency (>=8.12, Draft 2020-12). Install it with: npm install ajv",
+      HTTP_STATUS["KLICKD_E_SCHEMA"]
+    );
+  }
+  const ajv = new AjvCtor({ allErrors: true, strict: false, validateFormats: false });
+  for (const key of listBundledSchemas()) {
+    ajv.addSchema(SCHEMAS[key], `klickd:${key}`);
+  }
+  const validators = /* @__PURE__ */ new Map();
+  for (const key of listBundledSchemas()) {
+    validators.set(key, ajv.compile(SCHEMAS[key]));
+  }
+  ajvBundle = { validators };
+  return ajvBundle;
+}
+function keyFor(target, strict) {
+  return `${target}-${strict ? "strict" : "preview"}`;
+}
+function formatPath(instancePath) {
+  if (!instancePath || instancePath === "") return "<root>";
+  return instancePath.replace(/^\//, "");
+}
+async function validate(payload, options = {}) {
+  const strict = options.strict ?? true;
+  const target = options.target ?? "payload";
+  if (target !== "payload" && target !== "unified") {
+    throw new Error(`target must be 'payload' or 'unified', got ${String(target)}`);
+  }
+  const { validators } = await getAjv();
+  const validator = validators.get(keyFor(target, strict));
+  if (!validator) {
+    throw new Error(`No bundled validator for ${target}-${strict ? "strict" : "preview"}`);
+  }
+  if (validator(payload)) return;
+  const errors = validator.errors ?? [];
+  const summary = errors.slice(0, 8).map((e) => `${formatPath(e.instancePath)}: ${(e.message ?? "").slice(0, 200)}`);
+  const extra = errors.length > 8 ? ` (+${errors.length - 8} more)` : "";
+  throw new KlickdError(
+    "KLICKD_E_SCHEMA",
+    `v4 ${strict ? "strict" : "preview"} ${target} validation failed${extra}: ${summary.join(" | ")}`,
+    HTTP_STATUS["KLICKD_E_SCHEMA"]
+  );
+}
+async function validateIterErrors(payload, options = {}) {
+  const strict = options.strict ?? true;
+  const target = options.target ?? "payload";
+  if (target !== "payload" && target !== "unified") {
+    throw new Error(`target must be 'payload' or 'unified', got ${String(target)}`);
+  }
+  const { validators } = await getAjv();
+  const validator = validators.get(keyFor(target, strict));
+  if (!validator) {
+    throw new Error(`No bundled validator for ${target}-${strict ? "strict" : "preview"}`);
+  }
+  if (validator(payload)) return [];
+  return (validator.errors ?? []).map((e) => ({
+    path: formatPath(e.instancePath),
+    message: e.message ?? ""
+  }));
+}
+
+// src/migrate.ts
+var V3_SCHEMA_VERSIONS = /* @__PURE__ */ new Set([
+  "3.0",
+  "3.1",
+  "3.2",
+  "3.3",
+  "3.4",
+  "3.5"
+]);
+var V4_SCHEMA_VERSIONS = /* @__PURE__ */ new Set(["4.0", "4.0.0-preview.1"]);
+var RESERVED_PROFILE_KINDS = /* @__PURE__ */ new Set([
+  "learner",
+  "agent",
+  "team",
+  "robot",
+  "creator"
+]);
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function utcNowIso() {
+  const now = /* @__PURE__ */ new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${now.getUTCFullYear()}-${pad(now.getUTCMonth() + 1)}-${pad(now.getUTCDate())}T${pad(now.getUTCHours())}:${pad(now.getUTCMinutes())}:${pad(now.getUTCSeconds())}Z`;
+}
+function deepClone(value) {
+  return structuredClone(value);
+}
+function needsMigration(payload) {
+  if (!isPlainObject(payload)) return false;
+  const ver = payload["payload_schema_version"];
+  if (ver === void 0 || ver === null) return true;
+  if (typeof ver !== "string") return false;
+  if (V4_SCHEMA_VERSIONS.has(ver)) return false;
+  if (V3_SCHEMA_VERSIONS.has(ver)) return true;
+  return false;
+}
+function migratePayload(payload, options = {}) {
+  if (!isPlainObject(payload)) {
+    throw new KlickdError(
+      "KLICKD_E_SCHEMA",
+      `migratePayload requires a plain object payload; got ${typeof payload}`,
+      HTTP_STATUS["KLICKD_E_SCHEMA"]
+    );
+  }
+  const incomingVersion = payload["payload_schema_version"];
+  if (incomingVersion !== void 0 && typeof incomingVersion === "string" && !V3_SCHEMA_VERSIONS.has(incomingVersion) && !V4_SCHEMA_VERSIONS.has(incomingVersion)) {
+    throw new KlickdError(
+      "KLICKD_E_SCHEMA",
+      `migratePayload does not recognize payload_schema_version=${JSON.stringify(incomingVersion)}; expected v3.x (3.0..3.5) or v4 (4.0 / 4.0.0-preview.1)`,
+      HTTP_STATUS["KLICKD_E_SCHEMA"]
+    );
+  }
+  const out = deepClone(payload);
+  const {
+    sourceVersion,
+    migratedAt,
+    profileKind = "learner",
+    migrationReportRef,
+    backupRef
+  } = options;
+  if (typeof incomingVersion === "string" && V4_SCHEMA_VERSIONS.has(incomingVersion)) {
+    if (migrationReportRef === void 0 && backupRef === void 0) {
+      return out;
+    }
+    const existing = isPlainObject(out["migration"]) ? out["migration"] : {};
+    if (migrationReportRef !== void 0) {
+      existing["migration_report_ref"] = migrationReportRef;
+    }
+    if (backupRef !== void 0) {
+      existing["backup_ref"] = backupRef;
+    }
+    if (existing["source_version"] === void 0) {
+      existing["source_version"] = incomingVersion;
+    }
+    existing["migrated_at"] = migratedAt ?? utcNowIso();
+    out["migration"] = existing;
+    return out;
+  }
+  out["payload_schema_version"] = "4.0";
+  if (out["profile_kind"] === void 0) {
+    out["profile_kind"] = profileKind;
+  }
+  const migrationBlock = {
+    source_version: sourceVersion ?? (typeof incomingVersion === "string" ? incomingVersion : "3.x"),
+    migrated_at: migratedAt ?? utcNowIso()
+  };
+  if (migrationReportRef !== void 0) {
+    migrationBlock["migration_report_ref"] = migrationReportRef;
+  }
+  if (backupRef !== void 0) {
+    migrationBlock["backup_ref"] = backupRef;
+  }
+  out["migration"] = migrationBlock;
+  return out;
+}
+function migratePayloadIterWarnings(payload) {
+  const warnings = [];
+  if (!isPlainObject(payload)) {
+    warnings.push({ path: "<root>", message: "payload is not a JSON object" });
+    return warnings;
+  }
+  const ver = payload["payload_schema_version"];
+  if (ver === void 0) {
+    if (payload["domain_schema_version"] === void 0) {
+      warnings.push({
+        path: "<root>",
+        message: "no payload_schema_version and no domain_schema_version; pin sourceVersion explicitly when migrating"
+      });
+    }
+  } else if (typeof ver === "string" && !V3_SCHEMA_VERSIONS.has(ver) && !V4_SCHEMA_VERSIONS.has(ver)) {
+    warnings.push({
+      path: "/payload_schema_version",
+      message: `unknown payload_schema_version ${JSON.stringify(ver)}; migrator will refuse`
+    });
+  }
+  const ctx = payload["context"];
+  if (isPlainObject(ctx)) {
+    const decisions = ctx["decisions_locked"];
+    if (Array.isArray(decisions)) {
+      decisions.forEach((d, i) => {
+        if (typeof d === "string" && d.length > 1024) {
+          warnings.push({
+            path: `/context/decisions_locked/${i}`,
+            message: `entry exceeds 1024 chars (${d.length}); some readers will truncate`
+          });
+        }
+      });
+    }
+  }
+  const ethics = payload["ethics"];
+  const veto = payload["human_veto_policy"];
+  if (isPlainObject(ethics) && isPlainObject(veto)) {
+    const locked = ethics["locked_actions"];
+    const appliesTo = veto["applies_to"];
+    if (Array.isArray(locked) && Array.isArray(appliesTo)) {
+      const lockedSet = new Set(locked.filter((x) => typeof x === "string"));
+      const overlap = appliesTo.filter((x) => typeof x === "string" && lockedSet.has(x)).sort();
+      if (overlap.length > 0) {
+        warnings.push({
+          path: "/human_veto_policy/applies_to",
+          message: "overlaps with /ethics/locked_actions: " + overlap.map((x) => JSON.stringify(x)).join(", ")
+        });
+      }
+    }
+  }
+  const pk = payload["profile_kind"];
+  if (typeof pk === "string" && !RESERVED_PROFILE_KINDS.has(pk)) {
+    warnings.push({
+      path: "/profile_kind",
+      message: `non-reserved profile_kind ${JSON.stringify(pk)}; readers MAY treat as extension`
+    });
+  }
+  return warnings;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HTTP_STATUS,
   KlickdError,
+  getBundledSchema,
+  listBundledSchemas,
   loadKlickd,
-  saveKlickd
+  migratePayload,
+  migratePayloadIterWarnings,
+  needsMigration,
+  saveKlickd,
+  validate,
+  validateIterErrors
 });

package/dist/index.d.cts

@@ -84,9 +84,80 @@ interface KlickdPayload {
     context?: KlickdContext;
     knowledge?: KlickdKnowledge;
     memory?: KlickdMemoryEntry[];
+    profile_kind?: string;
+    preview?: string;
+    onboarding_trigger?: string;
+    media_profile?: KlickdMediaProfileV1 | Record<string, unknown> | null;
+    verification_gates?: KlickdVerificationGatesV1 | Record<string, KlickdGateLevel> | null;
+    human_veto_policy?: KlickdHumanVetoPolicy | null;
+    claim_sources?: KlickdClaimSources | null;
+    migration?: KlickdMigrationV1 | null;
+    risk_thresholds?: Record<string, unknown> | null;
+    preflight_checks?: unknown[] | null;
+    error_journal?: unknown[] | null;
+    verification_artifacts?: unknown[] | null;
+    contract_tests?: unknown[] | null;
+    success_criteria?: unknown;
+    reversibility?: Record<string, unknown> | null;
+    blast_radius?: Record<string, unknown> | null;
+    context_cost?: Record<string, unknown> | null;
+    gaming_profile?: Record<string, unknown> | null;
+    deprecated_fields?: Array<Record<string, unknown>> | null;
     /** Domain extension fields */
     [key: string]: unknown;
 }
+type KlickdMediaModality = 'voice' | 'image' | 'document' | 'embedding';
+interface KlickdMediaProfileEntryHash {
+    algo: 'blake3';
+    value: string;
+}
+interface KlickdMediaProfileEntry {
+    id: string;
+    modality: KlickdMediaModality;
+    hash: KlickdMediaProfileEntryHash;
+    label?: string;
+    language?: string;
+    uri?: string;
+    media_type?: string;
+    byte_size?: number;
+    duration_ms?: number;
+    bytes_b64?: string;
+    producer?: Record<string, unknown>;
+    consent?: Record<string, unknown>;
+}
+interface KlickdMediaProfileV1 {
+    version: 1;
+    entries: KlickdMediaProfileEntry[];
+}
+type KlickdGateLevel = 'silent' | 'warn' | 'confirm' | 'block' | 'require-owner';
+interface KlickdGateEntry {
+    action_class: string;
+    level: KlickdGateLevel;
+    id?: string;
+    reason?: string;
+}
+interface KlickdVerificationGatesV1 {
+    version: 1;
+    gates: KlickdGateEntry[];
+    user_default?: KlickdGateLevel;
+}
+interface KlickdHumanVetoPolicy {
+    applies_to?: string[];
+    second_party?: string | null;
+    min_level?: KlickdGateLevel;
+    rationale?: string;
+}
+interface KlickdClaimSources {
+    prefer?: string[];
+    require_citation_for?: string[];
+    records?: Array<Record<string, unknown>>;
+}
+interface KlickdMigrationV1 {
+    source_version?: string;
+    migrated_at?: string;
+    migration_report_ref?: string;
+    backup_ref?: string;
+}
 interface LoadKlickdOptions {
     passphrase?: string;
     /** Enable legacy v2.x PBKDF2-SHA256/600k reading. Default: false */
@@ -129,4 +200,94 @@ declare function saveKlickd(payload: KlickdPayload, options: SaveKlickdOptions):
  */
 declare function loadKlickd(input: string | Uint8Array, options?: LoadKlickdOptions): Promise<KlickdPayload>;
 
-export { type CipherName, HTTP_STATUS, type KdfName, type KlickdCipher, type KlickdContext, type KlickdDomain, type KlickdEnvelope, KlickdError, type KlickdErrorCode, type KlickdIdentity, type KlickdKdf, type KlickdKdfArgon2id, type KlickdKdfPbkdf2, type KlickdKnowledge, type KlickdMemoryEntry, type KlickdPayload, type LoadKlickdOptions, type MemoryModality, type MemoryRole, type SaveKlickdOptions, loadKlickd, saveKlickd };
+type ValidationTarget = 'payload' | 'unified';
+interface ValidateOptions {
+    /** True (default) = v4 GA strict schema; false = permissive preview. */
+    strict?: boolean;
+    /**
+     * "payload" (default) validates the inner payload schema.
+     * "unified" validates against the unified envelope+payload schema.
+     */
+    target?: ValidationTarget;
+}
+interface ValidationIssue {
+    /** JSON-pointer-like path ("" / "<root>" when at root). */
+    path: string;
+    /** Validator-produced human-readable message. */
+    message: string;
+}
+declare const SCHEMAS: {
+    readonly 'payload-strict': Record<string, unknown>;
+    readonly 'payload-preview': Record<string, unknown>;
+    readonly 'unified-strict': Record<string, unknown>;
+    readonly 'unified-preview': Record<string, unknown>;
+};
+type SchemaKey = keyof typeof SCHEMAS;
+/**
+ * Return a parsed copy of one of the four bundled v4 schemas. Provides the
+ * same affordance as Python `klickd.validate._load_schema` — useful for
+ * tooling that wants to introspect the bundled JSON without reaching back
+ * into the repo.
+ */
+declare function getBundledSchema(key: SchemaKey): Record<string, unknown>;
+/** List of bundled schema keys (parity with Python `_SCHEMA_FILES`). */
+declare function listBundledSchemas(): SchemaKey[];
+/**
+ * Validate a .klickd payload (or unified envelope+payload) against the v4
+ * JSON schema bundled with this package. Throws KlickdError(KLICKD_E_SCHEMA)
+ * on validation failure or when the optional `ajv` peer is missing.
+ *
+ * Mirrors Python `klickd.validate`. See packages/pypi/klickd/src/klickd/validate.py.
+ */
+declare function validate(payload: unknown, options?: ValidateOptions): Promise<void>;
+/**
+ * Non-throwing variant. Returns an array of {path, message} issues — empty
+ * when the payload is valid. Mirrors Python `validate_iter_errors`.
+ */
+declare function validateIterErrors(payload: unknown, options?: ValidateOptions): Promise<ValidationIssue[]>;
+
+interface MigrateOptions {
+    /** Override the recorded source_version. Defaults to the input's
+     *  payload_schema_version, or "3.x" when absent. */
+    sourceVersion?: string;
+    /** RFC 3339 UTC timestamp (must end with `Z`). Defaults to now().
+     *  Tests SHOULD pin this for reproducibility. */
+    migratedAt?: string;
+    /** Default "learner" (v3.x is implicitly "learner"). */
+    profileKind?: string;
+    /** Optional pointer (URI / path) to a human-authored migration report. */
+    migrationReportRef?: string;
+    /** Optional pointer to a backup of the pre-migration file. */
+    backupRef?: string;
+}
+interface MigrationWarning {
+    /** JSON-pointer-ish path; `<root>` for the top-level object. */
+    path: string;
+    /** Human-readable warning message. */
+    message: string;
+}
+type JsonObject = Record<string, unknown>;
+/**
+ * Return true iff `payload` is a v3.x payload that should be lifted to v4 GA.
+ *
+ * Mirrors Python `needs_migration`.
+ */
+declare function needsMigration(payload: unknown): boolean;
+/**
+ * Lift a v3.x .klickd payload to the v4 GA payload shape.
+ *
+ * Pure: the input is never mutated; a structurally cloned result is
+ * returned. Idempotent on already-v4 inputs (unchanged unless the caller
+ * passes pointer refs).
+ *
+ * Throws `KlickdError(KLICKD_E_SCHEMA)` when the input is not a plain
+ * object or carries an unrecognized `payload_schema_version`.
+ */
+declare function migratePayload(payload: unknown, options?: MigrateOptions): JsonObject;
+/**
+ * Return manual-review warnings without mutating `payload`. Mirrors
+ * Python `migrate_payload_iter_warnings`.
+ */
+declare function migratePayloadIterWarnings(payload: unknown): MigrationWarning[];
+
+export { type CipherName, HTTP_STATUS, type KdfName, type KlickdCipher, type KlickdClaimSources, type KlickdContext, type KlickdDomain, type KlickdEnvelope, KlickdError, type KlickdErrorCode, type KlickdGateEntry, type KlickdGateLevel, type KlickdHumanVetoPolicy, type KlickdIdentity, type KlickdKdf, type KlickdKdfArgon2id, type KlickdKdfPbkdf2, type KlickdKnowledge, type KlickdMediaModality, type KlickdMediaProfileEntry, type KlickdMediaProfileEntryHash, type KlickdMediaProfileV1, type KlickdMemoryEntry, type KlickdMigrationV1, type KlickdPayload, type KlickdVerificationGatesV1, type LoadKlickdOptions, type MemoryModality, type MemoryRole, type MigrateOptions, type MigrationWarning, type SaveKlickdOptions, type ValidateOptions, type ValidationIssue, type ValidationTarget, getBundledSchema, listBundledSchemas, loadKlickd, migratePayload, migratePayloadIterWarnings, needsMigration, saveKlickd, validate, validateIterErrors };

package/dist/index.d.ts

@@ -84,9 +84,80 @@ interface KlickdPayload {
     context?: KlickdContext;
     knowledge?: KlickdKnowledge;
     memory?: KlickdMemoryEntry[];
+    profile_kind?: string;
+    preview?: string;
+    onboarding_trigger?: string;
+    media_profile?: KlickdMediaProfileV1 | Record<string, unknown> | null;
+    verification_gates?: KlickdVerificationGatesV1 | Record<string, KlickdGateLevel> | null;
+    human_veto_policy?: KlickdHumanVetoPolicy | null;
+    claim_sources?: KlickdClaimSources | null;
+    migration?: KlickdMigrationV1 | null;
+    risk_thresholds?: Record<string, unknown> | null;
+    preflight_checks?: unknown[] | null;
+    error_journal?: unknown[] | null;
+    verification_artifacts?: unknown[] | null;
+    contract_tests?: unknown[] | null;
+    success_criteria?: unknown;
+    reversibility?: Record<string, unknown> | null;
+    blast_radius?: Record<string, unknown> | null;
+    context_cost?: Record<string, unknown> | null;
+    gaming_profile?: Record<string, unknown> | null;
+    deprecated_fields?: Array<Record<string, unknown>> | null;
     /** Domain extension fields */
     [key: string]: unknown;
 }
+type KlickdMediaModality = 'voice' | 'image' | 'document' | 'embedding';
+interface KlickdMediaProfileEntryHash {
+    algo: 'blake3';
+    value: string;
+}
+interface KlickdMediaProfileEntry {
+    id: string;
+    modality: KlickdMediaModality;
+    hash: KlickdMediaProfileEntryHash;
+    label?: string;
+    language?: string;
+    uri?: string;
+    media_type?: string;
+    byte_size?: number;
+    duration_ms?: number;
+    bytes_b64?: string;
+    producer?: Record<string, unknown>;
+    consent?: Record<string, unknown>;
+}
+interface KlickdMediaProfileV1 {
+    version: 1;
+    entries: KlickdMediaProfileEntry[];
+}
+type KlickdGateLevel = 'silent' | 'warn' | 'confirm' | 'block' | 'require-owner';
+interface KlickdGateEntry {
+    action_class: string;
+    level: KlickdGateLevel;
+    id?: string;
+    reason?: string;
+}
+interface KlickdVerificationGatesV1 {
+    version: 1;
+    gates: KlickdGateEntry[];
+    user_default?: KlickdGateLevel;
+}
+interface KlickdHumanVetoPolicy {
+    applies_to?: string[];
+    second_party?: string | null;
+    min_level?: KlickdGateLevel;
+    rationale?: string;
+}
+interface KlickdClaimSources {
+    prefer?: string[];
+    require_citation_for?: string[];
+    records?: Array<Record<string, unknown>>;
+}
+interface KlickdMigrationV1 {
+    source_version?: string;
+    migrated_at?: string;
+    migration_report_ref?: string;
+    backup_ref?: string;
+}
 interface LoadKlickdOptions {
     passphrase?: string;
     /** Enable legacy v2.x PBKDF2-SHA256/600k reading. Default: false */
@@ -129,4 +200,94 @@ declare function saveKlickd(payload: KlickdPayload, options: SaveKlickdOptions):
  */
 declare function loadKlickd(input: string | Uint8Array, options?: LoadKlickdOptions): Promise<KlickdPayload>;
 
-export { type CipherName, HTTP_STATUS, type KdfName, type KlickdCipher, type KlickdContext, type KlickdDomain, type KlickdEnvelope, KlickdError, type KlickdErrorCode, type KlickdIdentity, type KlickdKdf, type KlickdKdfArgon2id, type KlickdKdfPbkdf2, type KlickdKnowledge, type KlickdMemoryEntry, type KlickdPayload, type LoadKlickdOptions, type MemoryModality, type MemoryRole, type SaveKlickdOptions, loadKlickd, saveKlickd };
+type ValidationTarget = 'payload' | 'unified';
+interface ValidateOptions {
+    /** True (default) = v4 GA strict schema; false = permissive preview. */
+    strict?: boolean;
+    /**
+     * "payload" (default) validates the inner payload schema.
+     * "unified" validates against the unified envelope+payload schema.
+     */
+    target?: ValidationTarget;
+}
+interface ValidationIssue {
+    /** JSON-pointer-like path ("" / "<root>" when at root). */
+    path: string;
+    /** Validator-produced human-readable message. */
+    message: string;
+}
+declare const SCHEMAS: {
+    readonly 'payload-strict': Record<string, unknown>;
+    readonly 'payload-preview': Record<string, unknown>;
+    readonly 'unified-strict': Record<string, unknown>;
+    readonly 'unified-preview': Record<string, unknown>;
+};
+type SchemaKey = keyof typeof SCHEMAS;
+/**
+ * Return a parsed copy of one of the four bundled v4 schemas. Provides the
+ * same affordance as Python `klickd.validate._load_schema` — useful for
+ * tooling that wants to introspect the bundled JSON without reaching back
+ * into the repo.
+ */
+declare function getBundledSchema(key: SchemaKey): Record<string, unknown>;
+/** List of bundled schema keys (parity with Python `_SCHEMA_FILES`). */
+declare function listBundledSchemas(): SchemaKey[];
+/**
+ * Validate a .klickd payload (or unified envelope+payload) against the v4
+ * JSON schema bundled with this package. Throws KlickdError(KLICKD_E_SCHEMA)
+ * on validation failure or when the optional `ajv` peer is missing.
+ *
+ * Mirrors Python `klickd.validate`. See packages/pypi/klickd/src/klickd/validate.py.
+ */
+declare function validate(payload: unknown, options?: ValidateOptions): Promise<void>;
+/**
+ * Non-throwing variant. Returns an array of {path, message} issues — empty
+ * when the payload is valid. Mirrors Python `validate_iter_errors`.
+ */
+declare function validateIterErrors(payload: unknown, options?: ValidateOptions): Promise<ValidationIssue[]>;
+
+interface MigrateOptions {
+    /** Override the recorded source_version. Defaults to the input's
+     *  payload_schema_version, or "3.x" when absent. */
+    sourceVersion?: string;
+    /** RFC 3339 UTC timestamp (must end with `Z`). Defaults to now().
+     *  Tests SHOULD pin this for reproducibility. */
+    migratedAt?: string;
+    /** Default "learner" (v3.x is implicitly "learner"). */
+    profileKind?: string;
+    /** Optional pointer (URI / path) to a human-authored migration report. */
+    migrationReportRef?: string;
+    /** Optional pointer to a backup of the pre-migration file. */
+    backupRef?: string;
+}
+interface MigrationWarning {
+    /** JSON-pointer-ish path; `<root>` for the top-level object. */
+    path: string;
+    /** Human-readable warning message. */
+    message: string;
+}
+type JsonObject = Record<string, unknown>;
+/**
+ * Return true iff `payload` is a v3.x payload that should be lifted to v4 GA.
+ *
+ * Mirrors Python `needs_migration`.
+ */
+declare function needsMigration(payload: unknown): boolean;
+/**
+ * Lift a v3.x .klickd payload to the v4 GA payload shape.
+ *
+ * Pure: the input is never mutated; a structurally cloned result is
+ * returned. Idempotent on already-v4 inputs (unchanged unless the caller
+ * passes pointer refs).
+ *
+ * Throws `KlickdError(KLICKD_E_SCHEMA)` when the input is not a plain
+ * object or carries an unrecognized `payload_schema_version`.
+ */
+declare function migratePayload(payload: unknown, options?: MigrateOptions): JsonObject;
+/**
+ * Return manual-review warnings without mutating `payload`. Mirrors
+ * Python `migrate_payload_iter_warnings`.
+ */
+declare function migratePayloadIterWarnings(payload: unknown): MigrationWarning[];
+
+export { type CipherName, HTTP_STATUS, type KdfName, type KlickdCipher, type KlickdClaimSources, type KlickdContext, type KlickdDomain, type KlickdEnvelope, KlickdError, type KlickdErrorCode, type KlickdGateEntry, type KlickdGateLevel, type KlickdHumanVetoPolicy, type KlickdIdentity, type KlickdKdf, type KlickdKdfArgon2id, type KlickdKdfPbkdf2, type KlickdKnowledge, type KlickdMediaModality, type KlickdMediaProfileEntry, type KlickdMediaProfileEntryHash, type KlickdMediaProfileV1, type KlickdMemoryEntry, type KlickdMigrationV1, type KlickdPayload, type KlickdVerificationGatesV1, type LoadKlickdOptions, type MemoryModality, type MemoryRole, type MigrateOptions, type MigrationWarning, type SaveKlickdOptions, type ValidateOptions, type ValidationIssue, type ValidationTarget, getBundledSchema, listBundledSchemas, loadKlickd, migratePayload, migratePayloadIterWarnings, needsMigration, saveKlickd, validate, validateIterErrors };