@klickd/core 3.5.1 → 4.0.0

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 };

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
+    }
+  }
+}