@klickd/core 4.0.0-preview.1 → 4.0.0

package/dist/index.js

@@ -282,9 +282,264 @@ async function loadKlickd(input, options = {}) {
   }
   return payload;
 }
+
+// src/validate.ts
+import payloadStrict from "./klickd-payload-v4.schema-7UPTEJOY.json";
+import payloadPreview from "./klickd-payload-v4-preview.schema-W7RY72VP.json";
+import unifiedStrict from "./klickd-v4.schema-ZZGRYTLY.json";
+import unifiedPreview from "./klickd-v4-preview.schema-QHITWMK6.json";
+var SCHEMAS = {
+  "payload-strict": payloadStrict,
+  "payload-preview": payloadPreview,
+  "unified-strict": unifiedStrict,
+  "unified-preview": unifiedPreview
+};
+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;
+}
 export {
   HTTP_STATUS,
   KlickdError,
+  getBundledSchema,
+  listBundledSchemas,
   loadKlickd,
-  saveKlickd
+  migratePayload,
+  migratePayloadIterWarnings,
+  needsMigration,
+  saveKlickd,
+  validate,
+  validateIterErrors
 };

package/dist/klickd-payload-v4-preview.schema-W7RY72VP.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://klickd.app/schemas/v4-preview/klickd-payload.schema.json",
+  "title": "klickd Payload v4 Preview (PERMISSIVE, NON-NORMATIVE)",
+  "description": "PREVIEW schema for the .klickd v4 inner payload, targeting v4.0.0-preview.1. This schema is INTENTIONALLY PERMISSIVE: it accepts and preserves draft v4 structures (media_profile, verification_gates, human_veto_policy, claim_sources, verification_artifacts, migration, context_cost, profile_kind) without performing strict validation. additionalProperties is true at every level so that unknown fields round-trip verbatim. This schema MUST NOT be used to reject a file that is otherwise a valid v3.5.1 file. The normative schemas remain klickd-envelope-v3.schema.json and klickd-payload-v3.schema.json. See SPEC.md §33 and docs/rfcs/ for the design source.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "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 files."
+    },
+    "payload_schema_version": {
+      "type": "string",
+      "description": "Payload schema version. PERMISSIVE in this preview: any string is accepted. A future strict v4 schema MAY pin this to a concrete value."
+    },
+    "domain_schema_version": {
+      "type": "string",
+      "description": "Domain-specific schema version (e.g. 'education-1.2'). PERMISSIVE in this preview."
+    },
+    "profile_kind": {
+      "type": "string",
+      "description": "Top-level discriminator for the profile shape. Common values: 'learner', 'agent', 'team', 'robot'. v3.x is implicitly 'learner'; the preview makes this explicit and extensible. Custom strings are permitted."
+    },
+    "media_profile": {
+      "description": "RFC-001: portable, hash-referenced media context. Bytes live outside the .klickd file by default; the payload carries metadata, hashes, and (optionally) inline base64 below a documented threshold. PERMISSIVE: structure is not enforced here.",
+      "type": ["object", "array", "null"],
+      "additionalProperties": true
+    },
+    "verification_gates": {
+      "description": "RFC-002 v1: user's preferred friction profile, mapping action class to gate level (silent / warn / confirm / block / require-owner). PERMISSIVE: not enforced here.",
+      "type": ["object", "array", "null"],
+      "additionalProperties": true
+    },
+    "human_veto_policy": {
+      "description": "RFC-002 v1: standing rules about when a human MUST be in the loop, regardless of agent confidence. Overrides any lower gate. PERMISSIVE: not enforced here.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "claim_sources": {
+      "description": "RFC-002 v1 + v2-additive: declarative preferences for where to ground factual claims, and records of what was actually used. PERMISSIVE: not enforced here.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "verification_artifacts": {
+      "description": "RFC-002 §8b.8: pointer ledger of outputs already produced by expensive verification commands (test suites, builds, web fetches, DOI resolutions). MUST be a pointer ledger, not a payload sink. PERMISSIVE: structure is not enforced here.",
+      "type": ["array", "null"]
+    },
+    "error_journal": {
+      "description": "RFC-002 v1: append-only lessons learned that should influence future gate evaluation. PERMISSIVE: not enforced here.",
+      "type": ["array", "null"]
+    },
+    "risk_thresholds": {
+      "description": "RFC-002 v1: numeric / categorical knobs (e.g. public_reach, financial_amount_eur_max_silent). PERMISSIVE.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "preflight_checks": {
+      "description": "RFC-002 v1: small, named checks an agent SHOULD run before acting on certain classes. PERMISSIVE.",
+      "type": ["array", "null"]
+    },
+    "contract_tests": {
+      "description": "RFC-002 v2-additive: machine-checkable contract tests bound to action classes. PERMISSIVE.",
+      "type": ["array", "null"]
+    },
+    "success_criteria": {
+      "description": "RFC-002 v2-additive: declarative success criteria per action class. PERMISSIVE.",
+      "type": ["object", "array", "null"],
+      "additionalProperties": true
+    },
+    "reversibility": {
+      "description": "RFC-002 v2-additive: declared reversibility for action classes. PERMISSIVE.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "blast_radius": {
+      "description": "RFC-002 v2-additive: declared blast radius for action classes. PERMISSIVE.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    },
+    "migration": {
+      "description": "RFC-004: optional migration metadata block. Audit-only in this preview — no migration tooling ships with v4.0.0-preview.1. PERMISSIVE.",
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "properties": {
+        "source_version": {"type": "string"},
+        "migrated_at": {"type": "string"},
+        "migration_report_ref": {"type": "string"},
+        "backup_ref": {"type": "string"}
+      }
+    },
+    "context_cost": {
+      "description": "Research/benchmark track (benchmarks/context_cost/RFC.md): optional fields recording measured 'repeated context waste' for this profile. No normative semantics depend on this field. PERMISSIVE.",
+      "type": ["object", "null"],
+      "additionalProperties": true
+    }
+  }
+}