@kontextmind/kxm 0.6.0 → 0.7.0

package/plugins/kxm/src/price-calc.ts

@@ -29,10 +29,7 @@ export function findModelPrice(catalog: PriceCatalog, model: string, provider?:
   const normalizedProvider = provider?.trim().toLowerCase();
 
   for (const entry of catalog.models) {
-    if (normalizedProvider && entry.provider.toLowerCase() !== normalizedProvider) {
-      const matchesAlias = entry.aliases?.some((a) => a.toLowerCase() === normalizedModel);
-      if (!matchesAlias) continue;
-    }
+    if (normalizedProvider && entry.provider.toLowerCase() !== normalizedProvider) continue;
     if (entry.id.toLowerCase() === normalizedModel || entry.model.toLowerCase() === normalizedModel) {
       return entry;
     }
@@ -58,20 +55,21 @@ export function calculateModelCost(
   const row = findModelPrice(catalog, params.model, params.provider);
   if (!row || row.tiers.length === 0) return undefined;
 
-  const context = params.contextTokens ?? params.tokensIn ?? 0;
-  let selectedTier = row.tiers[0]!;
-  for (const tier of row.tiers) {
-    if (tier.upToContextTokens !== undefined && tier.upToContextTokens !== null && context > tier.upToContextTokens) {
-      continue;
-    }
-    selectedTier = tier;
-    break;
-  }
-
-  const tokensIn = params.tokensIn ?? 0;
-  const tokensOut = params.tokensOut ?? 0;
-  const cacheRead = params.cacheReadTokens ?? 0;
-  const cacheWrite = params.cacheWriteTokens ?? 0;
+  if (catalog.currency !== undefined && catalog.currency !== "USD") return undefined;
+  const validCount = (n: unknown): n is number => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+  const tokensIn = params.tokensIn;
+  const tokensOut = params.tokensOut;
+  const cacheRead = params.cacheReadTokens;
+  const cacheWrite = params.cacheWriteTokens;
+  if (!validCount(tokensIn) || !validCount(tokensOut) || !validCount(cacheRead) || !validCount(cacheWrite)) return undefined;
+  // Cumulative usage is not context occupancy. Only an unbounded flat tier can
+  // be selected when the caller has no context measurement.
+  const context = params.contextTokens;
+  if (context != null && !validCount(context)) return undefined;
+  const selectedTier = context == null
+    ? (row.tiers.length === 1 && row.tiers[0]!.upToContextTokens == null ? row.tiers[0] : undefined)
+    : row.tiers.find((tier) => tier.upToContextTokens == null || context <= tier.upToContextTokens);
+  if (!selectedTier || (cacheRead > 0 && selectedTier.cacheReadPerMillion == null) || (cacheWrite > 0 && selectedTier.cacheWritePerMillion == null)) return undefined;
 
   const cost =
     (tokensIn / 1_000_000) * selectedTier.inputPerMillion +
@@ -79,6 +77,7 @@ export function calculateModelCost(
     (cacheRead / 1_000_000) * (selectedTier.cacheReadPerMillion ?? 0) +
     (cacheWrite / 1_000_000) * (selectedTier.cacheWritePerMillion ?? 0);
 
+  if (!Number.isFinite(cost) || cost < 0) return undefined;
   const priceRef = `${catalog.date}#${row.id}`;
   return {
     costUsd: Math.round(cost * 1_000_000) / 1_000_000,

package/plugins/kxm/src/prices.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { parse } from "yaml";
 
@@ -40,6 +40,10 @@ export function parsePriceCatalog(text: string): PriceCatalog {
   if (typeof parsed.date !== "string" || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/.test(parsed.date)) {
     throw new Error("price catalog date must be YYYY-MM-DD");
   }
+  if (!Number.isFinite(Date.parse(parsed.date)) || new Date(parsed.date).toISOString().slice(0, 10) !== parsed.date) {
+    throw new Error("price catalog date must be a valid calendar date");
+  }
+  if (parsed.currency !== undefined && parsed.currency !== "USD") throw new Error("price catalog currency must be USD");
   if (typeof parsed.sha256 !== "string" || !/^(?:sha256:)?[a-f0-9]{64}$/.test(parsed.sha256)) {
     throw new Error("price catalog sha256 must be a 64-character hex digest");
   }
@@ -66,25 +70,34 @@ export function parsePriceCatalog(text: string): PriceCatalog {
     if (!Array.isArray(m.tiers) || m.tiers.length === 0) {
       throw new Error(`price catalog model ${m.id} must have at least one tier`);
     }
-    const tiers: PriceTier[] = m.tiers.map((tItem, tIndex) => {
+    const rawTiers = m.tiers;
+    let previousBound = 0;
+    const tiers: PriceTier[] = rawTiers.map((tItem, tIndex) => {
       if (!tItem || typeof tItem !== "object" || Array.isArray(tItem)) {
         throw new Error(`tier at index ${tIndex} for model ${m.id} must be an object`);
       }
       const t = tItem as Record<string, unknown>;
-      const inputRate = typeof t.inputPerMillion === "number" ? t.inputPerMillion : (typeof t.input === "number" ? t.input : undefined);
-      const outputRate = typeof t.outputPerMillion === "number" ? t.outputPerMillion : (typeof t.output === "number" ? t.output : undefined);
-      if (inputRate === undefined || inputRate < 0) {
-        throw new Error(`tier at index ${tIndex} for model ${m.id} must have a non-negative inputPerMillion`);
-      }
-      if (outputRate === undefined || outputRate < 0) {
-        throw new Error(`tier at index ${tIndex} for model ${m.id} must have a non-negative outputPerMillion`);
+      const rate = (field: string, short: string, required = false): number | null => {
+        const value = t[field] !== undefined ? t[field] : t[short];
+        if (value == null && !required) return null;
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+          throw new Error(`tier ${tIndex} for model ${m.id} requires finite non-negative ${field}`);
+        }
+        return value;
+      };
+      const bound = t.upToContextTokens ?? null;
+      if (bound === null) {
+        if (tIndex !== rawTiers.length - 1) throw new Error("unbounded price tier must be last");
+      } else {
+        if (typeof bound !== "number" || !Number.isSafeInteger(bound) || bound <= previousBound) throw new Error("price tier bounds must be positive and strictly increasing");
+        previousBound = bound;
       }
       return {
-        upToContextTokens: typeof t.upToContextTokens === "number" ? t.upToContextTokens : null,
-        inputPerMillion: inputRate,
-        outputPerMillion: outputRate,
-        cacheReadPerMillion: typeof t.cacheReadPerMillion === "number" ? t.cacheReadPerMillion : (typeof t.cacheRead === "number" ? t.cacheRead : null),
-        cacheWritePerMillion: typeof t.cacheWritePerMillion === "number" ? t.cacheWritePerMillion : (typeof t.cacheWrite === "number" ? t.cacheWrite : null),
+        upToContextTokens: bound,
+        inputPerMillion: rate("inputPerMillion", "input", true)!,
+        outputPerMillion: rate("outputPerMillion", "output", true)!,
+        cacheReadPerMillion: rate("cacheReadPerMillion", "cacheRead"),
+        cacheWritePerMillion: rate("cacheWritePerMillion", "cacheWrite"),
       };
     });
     return {
@@ -96,13 +109,16 @@ export function parsePriceCatalog(text: string): PriceCatalog {
     };
   });
 
-  return {
+  const catalog: PriceCatalog = {
     schema: PRICES_SCHEMA,
     date: parsed.date,
     sha256: parsed.sha256.replace(/^sha256:/, ""),
     currency: typeof parsed.currency === "string" ? parsed.currency : "USD",
     models,
   };
+  if (new Set(models.map((row) => row.id)).size !== models.length) throw new Error("duplicate price catalog model id");
+  if (hashPriceCatalog(catalog) !== catalog.sha256) throw new Error("price catalog hash mismatch");
+  return catalog;
 }
 
 export function loadPriceCatalog(rootOrPath: string): PriceCatalog | undefined {
@@ -110,7 +126,7 @@ export function loadPriceCatalog(rootOrPath: string): PriceCatalog | undefined {
     ? join(rootOrPath, ".kxm", "prices.yaml")
     : (existsSync(join(rootOrPath, "prices.yaml"))
       ? join(rootOrPath, "prices.yaml")
-      : (existsSync(rootOrPath) && !rootOrPath.endsWith("/") ? rootOrPath : undefined));
+      : (existsSync(rootOrPath) && statSync(rootOrPath).isFile() ? rootOrPath : undefined));
 
   if (!candidatePath || !existsSync(candidatePath)) {
     return undefined;

package/plugins/kxm/src/producers.ts

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+
+export interface ProducerPolicy { schema: "kxm.producers.v1"; updatedAt: string; promoted: string[]; demoted: string[]; enabled: string[]; disabled: string[]; roles: Record<string, string[]>; }
+const empty = (): ProducerPolicy => ({ schema: "kxm.producers.v1", updatedAt: new Date().toISOString(), promoted: [], demoted: [], enabled: [], disabled: [], roles: {} });
+export function loadProducerPolicy(root: string): ProducerPolicy {
+  const path = join(root, ".kxm", "producers.yaml");
+  if (!existsSync(path)) return empty();
+  const value = parse(readFileSync(path, "utf8")) as Partial<ProducerPolicy>;
+  if (value?.schema !== "kxm.producers.v1" || !Array.isArray(value.promoted) || !Array.isArray(value.demoted)) throw new Error("invalid .kxm/producers.yaml");
+  return { schema: "kxm.producers.v1", updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : new Date().toISOString(), promoted: value.promoted.filter((x): x is string => typeof x === "string"), demoted: value.demoted.filter((x): x is string => typeof x === "string"), enabled: Array.isArray(value.enabled) ? value.enabled.filter((x): x is string => typeof x === "string") : [], disabled: Array.isArray(value.disabled) ? value.disabled.filter((x): x is string => typeof x === "string") : [], roles: value.roles && typeof value.roles === "object" ? Object.fromEntries(Object.entries(value.roles).filter(([, v]) => Array.isArray(v)).map(([k, v]) => [k, (v as unknown[]).filter((x): x is string => typeof x === "string")])) : {} };
+}
+export function updateProducer(root: string, model: string, status: "promoted" | "demoted"): ProducerPolicy {
+  const policy = loadProducerPolicy(root);
+  policy.promoted = policy.promoted.filter((x) => x !== model);
+  policy.demoted = policy.demoted.filter((x) => x !== model);
+  policy[status].push(model);
+  policy.updatedAt = new Date().toISOString();
+  mkdirSync(join(root, ".kxm"), { recursive: true });
+  writeFileSync(join(root, ".kxm", "producers.yaml"), stringify(policy), "utf8");
+  return policy;
+}
+export function setModelState(root: string, model: string, state: "enabled" | "disabled", role?: string, removeRole = false): ProducerPolicy {
+  const policy = loadProducerPolicy(root);
+  policy.enabled = policy.enabled.filter((x) => x !== model);
+  policy.disabled = policy.disabled.filter((x) => x !== model);
+  policy[state].push(model);
+  if (role) {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/i.test(role)) throw new Error("invalid role id");
+    const rolePath = join(root, ".kxm", "roles", `${role}.yaml`);
+    let roleFile: Record<string, unknown> = {};
+    if (existsSync(rolePath)) {
+      const parsed = parse(readFileSync(rolePath, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) roleFile = parsed as Record<string, unknown>;
+    }
+    const roster = Array.isArray(roleFile.roster) ? roleFile.roster.filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)) : [];
+    const existing = roster.findIndex((entry) => entry.model === model);
+    if (removeRole) { if (existing >= 0) roster.splice(existing, 1); }
+    else if (existing < 0) roster.push({ model, enabled: true });
+    roleFile.schema ??= "kxm.role.v1"; roleFile.id ??= role; roleFile.roster = roster;
+    mkdirSync(join(root, ".kxm", "roles"), { recursive: true });
+    writeFileSync(rolePath, stringify(roleFile), "utf8");
+  }
+  policy.updatedAt = new Date().toISOString();
+  mkdirSync(join(root, ".kxm"), { recursive: true });
+  writeFileSync(join(root, ".kxm", "producers.yaml"), stringify(policy), "utf8");
+  return policy;
+}
+
+export function listRoleBindings(root: string): Record<string, string[]> {
+  const dir = join(root, ".kxm", "roles"); const result: Record<string, string[]> = {};
+  if (!existsSync(dir)) return result;
+  for (const file of readdirSync(dir).filter((name) => name.endsWith(".yaml"))) {
+    const role = file.slice(0, -5); const value = parse(readFileSync(join(dir, file), "utf8")) as { roster?: Array<{ model?: unknown }> };
+    result[role] = (value.roster ?? []).map((entry) => entry.model).filter((model): model is string => typeof model === "string");
+  }
+  return result;
+}
+
+export function isProducerAdmitted(root: string, modelId: string): boolean {
+  const policy = loadProducerPolicy(root);
+  return policy.enabled.includes(modelId) && policy.promoted.includes(modelId) && !policy.disabled.includes(modelId) && !policy.demoted.includes(modelId);
+}
+
+export function listInventoryModels(root: string): string[] {
+  const path = join(root, ".kxm", "models", "inventory.yaml");
+  if (!existsSync(path)) return [];
+  const value = parse(readFileSync(path, "utf8")) as { models?: Array<{ id?: unknown }> };
+  return (value.models ?? []).map((m) => m.id).filter((id): id is string => typeof id === "string");
+}

package/plugins/kxm/src/restricted-yaml.d.mts

@@ -0,0 +1,31 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+export type JsonObject = { [key: string]: JsonValue };
+
+export interface VnextYamlLimits {
+  maxDocumentBytes: number;
+  maxDepth: number;
+  maxScalarBytes: number;
+  maxCollectionItems: number;
+  maxTotalNodes: number;
+  maxKeys: number;
+}
+
+export const VNEXT_YAML_LIMITS: Readonly<VnextYamlLimits>;
+
+export interface RestrictedYamlIssue {
+  phase: "parse";
+  code: string;
+  file: string;
+  message: string;
+}
+
+export class RestrictedYamlError extends Error {
+  readonly issues: readonly RestrictedYamlIssue[];
+  constructor(issues: readonly RestrictedYamlIssue[]);
+}
+
+export function parseRestrictedYaml(
+  input: string | Uint8Array,
+  label?: string,
+  limits?: Readonly<VnextYamlLimits>,
+): JsonObject;

package/plugins/kxm/src/restricted-yaml.mjs

@@ -0,0 +1,145 @@
+import { isAlias, isCollection, isMap, isScalar, parseDocument, visit } from "yaml";
+
+/** Restricted JSON-compatible YAML limits used by vNext configuration. */
+export const VNEXT_YAML_LIMITS = Object.freeze({
+  maxDocumentBytes: 256 * 1024,
+  maxDepth: 32,
+  maxScalarBytes: 64 * 1024,
+  maxCollectionItems: 4096,
+  maxTotalNodes: 16_384,
+  maxKeys: 8192,
+});
+
+const ALLOWED_YAML_TAGS = new Set([
+  "tag:yaml.org,2002:map",
+  "tag:yaml.org,2002:seq",
+  "tag:yaml.org,2002:str",
+  "tag:yaml.org,2002:null",
+  "tag:yaml.org,2002:bool",
+  "tag:yaml.org,2002:int",
+  "tag:yaml.org,2002:float",
+]);
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function sortIssues(issues) {
+  return [...issues].sort((left, right) => compareCodeUnits(left.file, right.file)
+    || compareCodeUnits(left.phase, right.phase)
+    || compareCodeUnits(left.code, right.code)
+    || compareCodeUnits(left.message, right.message));
+}
+
+function issue(phase, code, file, message) {
+  return { phase, code, file, message };
+}
+
+export class RestrictedYamlError extends Error {
+  /**
+   * @param {readonly { phase: string, code: string, file: string, message: string }[]} issues
+   */
+  constructor(issues) {
+    const sorted = sortIssues(issues);
+    super(sorted.map((entry) => `${entry.file}: ${entry.code}: ${entry.message}`).join("\n"));
+    this.name = "RestrictedYamlError";
+    this.issues = sorted;
+  }
+}
+
+function fail(phase, code, file, message) {
+  throw new RestrictedYamlError([issue(phase, code, file, message)]);
+}
+
+function decodeUtf8(input, label) {
+  if (typeof input === "string") return input;
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(input);
+  } catch {
+    fail("parse", "invalid_utf8", label, "document is not valid UTF-8");
+  }
+}
+
+function isJsonObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertJsonValue(value, label, path = "$", seen = new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) fail("parse", "non_json_number", label, `${path} is not a finite JSON number`);
+    return;
+  }
+  if (!value || typeof value !== "object") fail("parse", "non_json_value", label, `${path} is not JSON-compatible`);
+  if (seen.has(value)) fail("parse", "cyclic_value", label, `${path} is cyclic`);
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const [index, candidate] of value.entries()) assertJsonValue(candidate, label, `${path}[${index}]`, seen);
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      fail("parse", "constructed_object", label, `${path} has a forbidden constructed type`);
+    }
+    for (const [key, candidate] of Object.entries(value)) assertJsonValue(candidate, label, `${path}.${key}`, seen);
+  }
+  seen.delete(value);
+}
+
+/** Parse the restricted, JSON-compatible YAML profile used by all vNext configuration. */
+export function parseRestrictedYaml(
+  input,
+  label = "<yaml>",
+  limits = VNEXT_YAML_LIMITS,
+) {
+  const byteLength = typeof input === "string" ? Buffer.byteLength(input, "utf8") : input.byteLength;
+  if (byteLength > limits.maxDocumentBytes) {
+    fail("parse", "document_too_large", label, `document exceeds ${limits.maxDocumentBytes} bytes`);
+  }
+  const text = decodeUtf8(input, label);
+  const document = parseDocument(text, {
+    customTags: [],
+    strict: true,
+    uniqueKeys: true,
+  });
+  if (document.errors.length > 0) {
+    fail("parse", "invalid_yaml", label, document.errors.map((error) => error.message).join("; "));
+  }
+  if (document.warnings.length > 0) {
+    fail("parse", "yaml_warning", label, document.warnings.map((warning) => warning.message).join("; "));
+  }
+
+  let nodes = 0;
+  let keys = 0;
+  visit(document, (_key, node, path) => {
+    nodes += 1;
+    if (nodes > limits.maxTotalNodes) fail("parse", "node_limit", label, `document exceeds ${limits.maxTotalNodes} nodes`);
+    if (path.length > limits.maxDepth) fail("parse", "depth_limit", label, `document exceeds nesting depth ${limits.maxDepth}`);
+    if (isAlias(node)) fail("parse", "alias_forbidden", label, "aliases are forbidden");
+    if (node && typeof node === "object" && "anchor" in node && typeof node.anchor === "string") {
+      fail("parse", "anchor_forbidden", label, "anchors are forbidden");
+    }
+    if (isCollection(node) && node.items.length > limits.maxCollectionItems) {
+      fail("parse", "collection_limit", label, `collection exceeds ${limits.maxCollectionItems} items`);
+    }
+    if (isMap(node)) {
+      keys += node.items.length;
+      if (keys > limits.maxKeys) fail("parse", "key_limit", label, `document exceeds ${limits.maxKeys} mapping keys`);
+      for (const pair of node.items) {
+        if (!isScalar(pair.key) || typeof pair.key.value !== "string") {
+          fail("parse", "non_string_key", label, "mapping keys must be strings");
+        }
+      }
+    }
+    if (isScalar(node) && typeof node.value === "string" && Buffer.byteLength(node.value, "utf8") > limits.maxScalarBytes) {
+      fail("parse", "scalar_limit", label, `scalar exceeds ${limits.maxScalarBytes} bytes`);
+    }
+    if (node && typeof node === "object" && "tag" in node && typeof node.tag === "string" && !ALLOWED_YAML_TAGS.has(node.tag)) {
+      fail("parse", "tag_forbidden", label, `tag ${node.tag} is forbidden`);
+    }
+  });
+
+  const value = document.toJS({ maxAliasCount: 0 });
+  assertJsonValue(value, label);
+  if (!isJsonObject(value)) fail("parse", "root_not_object", label, "resource root must be a mapping");
+  return value;
+}