@klickd/core 3.0.1 → 4.0.0-preview.1

package/README.md

@@ -4,9 +4,11 @@ Official JavaScript/TypeScript library for reading and writing `.klickd` portabl
 
 **One soul. Any model. Any body.**
 
+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.20262530.svg)](https://doi.org/10.5281/zenodo.20262530)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20320480.svg)](https://doi.org/10.5281/zenodo.20320480)
 
 ---
 
@@ -76,6 +78,40 @@ const payload = await loadKlickd(fileBytes, {
 
 ---
 
+## `.klickd` v4 preview fields (additive, non-GA)
+
+This library currently targets the **v3** envelope and is **stable at v3.5.1**.
+The v4 preview track (`v4.0.0-preview.1`, NOT GA) introduces additive payload
+fields such as `profile_kind`, `media_profile`, `verification_gates`,
+`claim_sources`, `verification_artifacts`, `migration`, and `context_cost`.
+
+These fields are **preserved verbatim** on round-trip — `loadKlickd` returns
+the raw decrypted JSON object and `saveKlickd` re-encrypts it without
+filtering unknown keys. The `KlickdPayload` type carries an open
+`[key: string]: unknown` index signature so v4 preview fields type-check as
+additive properties. Strict v4 validation, migrations, and business-logic
+helpers are intentionally **not** implemented yet.
+
+```typescript
+const v4PreviewPayload: KlickdPayload = {
+  payload_schema_version: '4.0.0-preview.1',
+  domain_schema_version: '1.0.0',
+  profile_kind: 'learner',
+  verification_gates: { public_post: 'confirm' },
+  // ... any additional v4 preview fields are preserved on save/load
+};
+
+const recovered = await loadKlickd(
+  await saveKlickd(v4PreviewPayload, { passphrase: 'my-passphrase' }),
+  { passphrase: 'my-passphrase' },
+);
+// recovered deep-equals v4PreviewPayload
+```
+
+See `SPEC.md §33` and `examples/v4-preview/` for preview-track details.
+
+---
+
 ## Cryptographic specification (v3.0)
 
 | Parameter     | Value                                   |
@@ -105,9 +141,10 @@ const payload = await loadKlickd(fileBytes, {
 
 ## Links
 
+- 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.20262530](https://doi.org/10.5281/zenodo.20262530)
+- 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)
 
 ---

package/dist/index.cjs

@@ -275,10 +275,14 @@ async function loadKlickd(input, options = {}) {
     );
   }
   const cipherName = envelope.cipher.name;
-  if (cipherName !== "AES-256-GCM") {
+  if (cipherName === "aes-256-gcm") {
+    console.warn(
+      "KLICKD_W_DEPRECATED: cipher.name='aes-256-gcm' (lowercase) is legacy; canonical is 'AES-256-GCM'. Re-encode to upgrade."
+    );
+  } else if (cipherName !== "AES-256-GCM") {
     throw new KlickdError(
       "KLICKD_E_FORMAT",
-      `Unsupported cipher: ${cipherName}. Only AES-256-GCM is supported in v3.0.`,
+      `Unsupported cipher: ${cipherName}. Only AES-256-GCM is supported in v3.0 (legacy 'aes-256-gcm' also accepted).`,
       HTTP_STATUS["KLICKD_E_FORMAT"]
     );
   }

package/dist/index.d.cts

@@ -75,7 +75,12 @@ interface KlickdPayload {
     domain_schema_version: string;
     identity?: KlickdIdentity;
     agent_instructions?: string;
-    user_preferences?: Record<string, unknown>;
+    /**
+     * Advisory user-preference briefing. Canonical type = string (SPEC.md §22.6,
+     * max 32,768 bytes UTF-8). Object form retained for backward compatibility
+     * with pre-v3.4 files; new producers SHOULD emit the string form.
+     */
+    user_preferences?: string | Record<string, unknown>;
     context?: KlickdContext;
     knowledge?: KlickdKnowledge;
     memory?: KlickdMemoryEntry[];

package/dist/index.d.ts

@@ -75,7 +75,12 @@ interface KlickdPayload {
     domain_schema_version: string;
     identity?: KlickdIdentity;
     agent_instructions?: string;
-    user_preferences?: Record<string, unknown>;
+    /**
+     * Advisory user-preference briefing. Canonical type = string (SPEC.md §22.6,
+     * max 32,768 bytes UTF-8). Object form retained for backward compatibility
+     * with pre-v3.4 files; new producers SHOULD emit the string form.
+     */
+    user_preferences?: string | Record<string, unknown>;
     context?: KlickdContext;
     knowledge?: KlickdKnowledge;
     memory?: KlickdMemoryEntry[];

package/dist/index.js

@@ -236,10 +236,14 @@ async function loadKlickd(input, options = {}) {
     );
   }
   const cipherName = envelope.cipher.name;
-  if (cipherName !== "AES-256-GCM") {
+  if (cipherName === "aes-256-gcm") {
+    console.warn(
+      "KLICKD_W_DEPRECATED: cipher.name='aes-256-gcm' (lowercase) is legacy; canonical is 'AES-256-GCM'. Re-encode to upgrade."
+    );
+  } else if (cipherName !== "AES-256-GCM") {
     throw new KlickdError(
       "KLICKD_E_FORMAT",
-      `Unsupported cipher: ${cipherName}. Only AES-256-GCM is supported in v3.0.`,
+      `Unsupported cipher: ${cipherName}. Only AES-256-GCM is supported in v3.0 (legacy 'aes-256-gcm' also accepted).`,
       HTTP_STATUS["KLICKD_E_FORMAT"]
     );
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klickd/core",
-  "version": "3.0.1",
+  "version": "4.0.0-preview.1",
   "description": "Official JavaScript/TypeScript library for reading and writing .klickd portable AI context files",
   "keywords": [
     "klickd",
@@ -22,9 +22,9 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     }
   },
   "files": [