@klickd/core 4.0.0-preview.1 → 4.0.1

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)
 
 ---
 
@@ -110,6 +110,42 @@ const recovered = await loadKlickd(
 
 See `SPEC.md §33` and `examples/v4-preview/` for preview-track details.
 
+### Starter `.klickd` skills (v4.0 envelope — non-normative)
+
+Four real, structured, downloadable starter `.klickd` skills ship under [`examples/v4/starter-skills/`](https://github.com/Davincc77/klickdskill/tree/main/examples/v4/starter-skills):
+
+- [`user.klickd`](https://github.com/Davincc77/klickdskill/blob/main/examples/v4/starter-skills/user.klickd) — `x.klickd/user` (transversal base)
+- [`student.klickd`](https://github.com/Davincc77/klickdskill/blob/main/examples/v4/starter-skills/student.klickd) — `x.klickd/student` (education)
+- [`research.klickd`](https://github.com/Davincc77/klickdskill/blob/main/examples/v4/starter-skills/research.klickd) — `x.klickd/research` (research / evidence discipline)
+- [`coding.klickd`](https://github.com/Davincc77/klickdskill/blob/main/examples/v4/starter-skills/coding.klickd) — `x.klickd/coding` (software engineering)
+
+Each skill carries `base_transversal_core`, framework-anchored `competencies[]` (ESCO / DigComp / LifeComp / EQF / CEFR / SFIA), `levels[]`, `mastery[]` (pointer-only), `source_policy`, `evidence_policy`, `verification_gates`, `human_authority`, and a `structured_memory` slice scoped to `memory.x_klickd.<pack>`. They are **non-normative**, **do not claim v4.1 GA**, and trigger **no release**. SHA-256 manifest in [`manifest.json`](https://github.com/Davincc77/klickdskill/blob/main/examples/v4/starter-skills/manifest.json); offline verifier `scripts/verify_starter_skills.py`.
+
+#### Bundled in `@klickd/core` 4.0.1
+
+Starting with **`@klickd/core` 4.0.1** (a packaging-only patch — the stable
+spec release remains **v4.0.0**), these four starter `.klickd` skills are
+shipped inside the npm tarball under `starter-skills/` and exposed through a
+small helper API. The on-the-wire `.klickd` format, the bundled JSON schemas,
+and the spec are unchanged from v4.0.0. This patch does **not** ship any v4.1
+material and does **not** carry any Chimera branding.
+
+```typescript
+import {
+  listStarterSkills,
+  getStarterSkillBytes,
+  getStarterSkillsManifest,
+  getStarterSkillsDir,
+} from '@klickd/core';
+
+listStarterSkills();
+// → ['coding.klickd', 'research.klickd', 'student.klickd', 'user.klickd']
+
+const bytes = getStarterSkillBytes('user.klickd');
+const manifest = getStarterSkillsManifest();
+const dir = getStarterSkillsDir(); // absolute path to bundled starter-skills/
+```
+
 ---
 
 ## Cryptographic specification (v3.0)
@@ -144,12 +180,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,19 @@ var index_exports = {};
 __export(index_exports, {
   HTTP_STATUS: () => HTTP_STATUS,
   KlickdError: () => KlickdError,
+  getBundledSchema: () => getBundledSchema,
+  getStarterSkillBytes: () => getStarterSkillBytes,
+  getStarterSkillsDir: () => getStarterSkillsDir,
+  getStarterSkillsManifest: () => getStarterSkillsManifest,
+  listBundledSchemas: () => listBundledSchemas,
+  listStarterSkills: () => listStarterSkills,
   loadKlickd: () => loadKlickd,
-  saveKlickd: () => saveKlickd
+  migratePayload: () => migratePayload,
+  migratePayloadIterWarnings: () => migratePayloadIterWarnings,
+  needsMigration: () => needsMigration,
+  saveKlickd: () => saveKlickd,
+  validate: () => validate,
+  validateIterErrors: () => validateIterErrors
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -321,10 +332,298 @@ 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;
+}
+
+// src/starter-skills.ts
+var import_node_url = require("url");
+var import_node_path = require("path");
+var import_node_fs = require("fs");
+var import_meta = {};
+function starterSkillsDir() {
+  const here = (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+  return (0, import_node_path.join)(here, "..", "starter-skills");
+}
+function getStarterSkillsDir() {
+  return starterSkillsDir();
+}
+function listStarterSkills() {
+  return (0, import_node_fs.readdirSync)(starterSkillsDir()).filter((name) => name.endsWith(".klickd")).sort();
+}
+function getStarterSkillBytes(name) {
+  if (!name.endsWith(".klickd")) {
+    throw new Error(`starter skill name must end with .klickd: ${name}`);
+  }
+  if (name.includes("/") || name.includes("\\") || name.includes("..")) {
+    throw new Error(`invalid starter skill name: ${name}`);
+  }
+  return new Uint8Array((0, import_node_fs.readFileSync)((0, import_node_path.join)(starterSkillsDir(), name)));
+}
+function getStarterSkillsManifest() {
+  const raw = (0, import_node_fs.readFileSync)((0, import_node_path.join)(starterSkillsDir(), "manifest.json"), "utf8");
+  return JSON.parse(raw);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HTTP_STATUS,
   KlickdError,
+  getBundledSchema,
+  getStarterSkillBytes,
+  getStarterSkillsDir,
+  getStarterSkillsManifest,
+  listBundledSchemas,
+  listStarterSkills,
   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,115 @@ 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[];
+
+interface StarterSkillEntry {
+    id: string;
+    file: string;
+    pack_version: string;
+    bytes: number;
+    sha256_file: string;
+    sha256_canonical_json: string;
+}
+interface StarterSkillManifest {
+    manifest_version: string;
+    kind: string;
+    non_normative: boolean;
+    claims_v41_ga: boolean;
+    packs: StarterSkillEntry[];
+    [key: string]: unknown;
+}
+declare function getStarterSkillsDir(): string;
+declare function listStarterSkills(): string[];
+declare function getStarterSkillBytes(name: string): Uint8Array;
+declare function getStarterSkillsManifest(): StarterSkillManifest;
+
+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 StarterSkillEntry, type StarterSkillManifest, type ValidateOptions, type ValidationIssue, type ValidationTarget, getBundledSchema, getStarterSkillBytes, getStarterSkillsDir, getStarterSkillsManifest, listBundledSchemas, listStarterSkills, loadKlickd, migratePayload, migratePayloadIterWarnings, needsMigration, saveKlickd, validate, validateIterErrors };