@k2b/cloud 0.10.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -89,50 +89,49 @@
     "typecheck": "tsc -p tsconfig.json --noEmit --pretty false"
   },
   "dependencies": {
-    "@firecrawl/anydoc": "0.1.9",
-    "@napi-rs/canvas": "1.0.8",
+    "@firecrawl/anydoc": "0.2.4",
+    "@napi-rs/canvas": "1.0.9",
     "pdfjs-dist": "6.3.289",
     "@hono/standard-validator": "0.2.2",
-    "@simplewebauthn/server": "13.3.2",
-    "@tabler/icons": "3.46.0",
+    "@simplewebauthn/server": "14.0.2",
+    "@tabler/icons": "3.47.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.12.1",
     "@k2b/ssr": "0.14.0",
     "@k2b/ui": "0.5.0",
     "@k2b/stdlib": "0.25.0",
-    "@k2b/sync": "6.4.0",
+    "@k2b/sync": "6.5.0",
     "@nats-io/transport-node": "3.4.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "bun-plugin-tailwind": "0.1.2",
     "hono-openapi": "1.3.1",
-    "jose": "6.2.5",
-    "katex": "0.16.47",
-    "liquidjs": "10.27.2",
+    "jose": "6.2.12",
+    "katex": "0.18.7",
+    "liquidjs": "10.29.0",
     "marked": "17.0.6",
     "mermaid": "11.16.0",
-    "nodemailer": "9.1.1",
-    "postcss": "8.5.25",
+    "nodemailer": "10.0.10",
+    "postcss": "8.5.28",
     "reflect-metadata": "0.2.2",
-    "sanitize-html": "2.17.6",
-    "seroval": "1.6.0",
+    "sanitize-html": "2.17.7",
+    "seroval": "1.6.7",
     "tailwindcss": "4.3.3",
     "web-push": "3.6.7",
-    "web-vitals": "6.2.1",
-    "yaml": "2.9.0",
+    "web-vitals": "6.2.2",
+    "yaml": "2.9.1",
     "hash-wasm": "4.12.0",
-    "@types/nodemailer": "7.0.12",
     "@types/sanitize-html": "2.16.1",
     "@types/web-push": "3.6.4"
   },
   "devDependencies": {
-    "@babel/core": "7.29.7",
-    "@babel/preset-typescript": "7.29.7",
+    "@babel/core": "8.0.6",
+    "@babel/preset-typescript": "8.0.1",
     "@types/bun": "1.4.2",
-    "babel-preset-solid": "1.9.12",
-    "hono": "4.12.32",
-    "solid-js": "1.9.14",
+    "babel-preset-solid": "1.9.15",
+    "hono": "4.13.8",
+    "solid-js": "1.9.15",
     "typescript": "5.9.3",
-    "zod": "4.6.2"
+    "zod": "4.6.5"
   },
   "peerDependencies": {
     "hono": "^4.12.25",

package/src/ai/settings-messages.ts

@@ -0,0 +1,129 @@
+import { i18n } from "@k2b/stdlib";
+import type { AiModelReferenceSetting, AiSettingsIssue } from "./settings";
+
+type Reference = { setting: string; profile: string; next: string };
+
+const catalog = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      notSaved: "The AI settings were not saved. Resolve the problems below and save again.",
+      defaultModel: "default model",
+      backgroundModel: "background model",
+      workflowModel: "workflow model",
+      visionModel: "Vision tool model",
+      audioModel: "audio model",
+      selectAnother: ({ setting }: { setting: string }) => `Select another ${setting}`,
+      useDefaultModel: "use the default model instead",
+      useBackgroundModel: "use the background model instead",
+      disableVisionFallback: "disable the view_image fallback",
+      disableAudio: "disable audio transcription",
+      or: ({ first, second }: { first: string; second: string }) => `${first} or ${second}`,
+      modelRequired: "Choose a default model while AI is enabled.",
+      profileMissing: ({ setting, profile, next }: Reference) =>
+        `The ${setting} still references “${profile}”. ${next} before removing this profile.`,
+      profileDisabled: ({ setting, profile, next }: Reference) =>
+        `The ${setting} uses “${profile}”, which is disabled. ${next}, or enable the profile again.`,
+      noVision: ({ setting, profile, next }: Reference) => `“${profile}” does not support Vision, so it cannot be the ${setting}. ${next}.`,
+      transcriptionOnly: ({ setting, profile, next }: Reference) =>
+        `“${profile}” only transcribes audio, so it cannot be the ${setting}. ${next}.`,
+      noTranscription: ({ setting, profile, next }: Reference) =>
+        `“${profile}” does not transcribe audio, so it cannot be the ${setting}. ${next}.`,
+      credentialMissing: ({ profile }: { profile: string }) =>
+        `“${profile}” needs a provider API key. Enter the key in the profile or disable the profile.`,
+    },
+    de: {
+      notSaved: "Die KI-Einstellungen wurden nicht gespeichert. Behebe die folgenden Probleme und speichere erneut.",
+      defaultModel: "Standardmodell",
+      backgroundModel: "Hintergrundmodell",
+      workflowModel: "Workflow-Modell",
+      visionModel: "Modell für das Bildwerkzeug",
+      audioModel: "Audio-Modell",
+      selectAnother: ({ setting }) => `Wähle ein anderes ${setting}`,
+      useDefaultModel: "verwende stattdessen das Standardmodell",
+      useBackgroundModel: "verwende stattdessen das Hintergrundmodell",
+      disableVisionFallback: "deaktiviere den view_image-Fallback",
+      disableAudio: "deaktiviere die Audio-Transkription",
+      or: ({ first, second }) => `${first} oder ${second}`,
+      modelRequired: "Wähle ein Standardmodell, solange KI aktiviert ist.",
+      profileMissing: ({ setting, profile, next }) =>
+        `Das ${setting} verweist noch auf „${profile}“. ${next}, bevor du dieses Profil entfernst.`,
+      profileDisabled: ({ setting, profile, next }) =>
+        `Das ${setting} verwendet „${profile}“, aber dieses Profil ist deaktiviert. ${next}. Du kannst das Profil auch wieder aktivieren.`,
+      noVision: ({ setting, profile, next }) =>
+        `„${profile}“ unterstützt keine Bildverarbeitung und kann nicht als ${setting} verwendet werden. ${next}.`,
+      transcriptionOnly: ({ setting, profile, next }) =>
+        `„${profile}“ transkribiert nur Audio und kann nicht als ${setting} verwendet werden. ${next}.`,
+      noTranscription: ({ setting, profile, next }) =>
+        `„${profile}“ transkribiert kein Audio und kann nicht als ${setting} verwendet werden. ${next}.`,
+      credentialMissing: ({ profile }) =>
+        `„${profile}“ benötigt einen API-Schlüssel des Anbieters. Gib den Schlüssel im Profil ein oder deaktiviere das Profil.`,
+    },
+  },
+});
+
+type Messages = ReturnType<typeof catalog.resolve>["t"];
+
+const settingNoun = (t: Messages, setting: AiModelReferenceSetting): string =>
+  ({
+    "ai.default_model_id": t.defaultModel,
+    "ai.background_model_id": t.backgroundModel,
+    "ai.workflow_model_id": t.workflowModel,
+    "ai.vision_model_id": t.visionModel,
+    "ai.audio_model_id": t.audioModel,
+  })[setting];
+
+/** The way out that keeps the feature working without this profile, if the setting is optional. */
+const alternative = (t: Messages, setting: AiModelReferenceSetting): string | undefined =>
+  ({
+    "ai.default_model_id": undefined,
+    "ai.background_model_id": t.useDefaultModel,
+    "ai.workflow_model_id": t.useBackgroundModel,
+    "ai.vision_model_id": t.disableVisionFallback,
+    "ai.audio_model_id": t.disableAudio,
+  })[setting];
+
+export type AiSettingsIssueWithMessage = AiSettingsIssue & { message: string };
+
+/**
+ * Turn validation issues into request-localized, actionable messages.
+ *
+ * `profiles` should list the prospective profiles first and the stored ones
+ * after them, so a profile that is being removed still has its label. Only
+ * ids and labels are read; provider keys never reach the messages.
+ */
+export const describeAiSettingsIssues = (
+  issues: readonly AiSettingsIssue[],
+  options: { locale?: string | null; profiles: ReadonlyArray<{ id: string; label: string }> },
+): { issues: AiSettingsIssueWithMessage[]; errors: Record<string, string> } => {
+  const t = catalog.resolve(options.locale ? [options.locale] : []).t;
+  const labelOf = (profileId: string) => options.profiles.find((profile) => profile.id === profileId)?.label ?? profileId;
+
+  const described = issues.map((issue): AiSettingsIssueWithMessage => {
+    if (issue.code === "model_required") return { ...issue, message: t.modelRequired };
+    const profile = labelOf(issue.profileId);
+    if (issue.code === "provider_credential_missing") return { ...issue, message: t.credentialMissing({ profile }) };
+
+    const setting = settingNoun(t, issue.setting);
+    const other = alternative(t, issue.setting);
+    const select = t.selectAnother({ setting });
+    const reference = { setting, profile, next: other ? t.or({ first: select, second: other }) : select };
+    if (issue.code === "model_profile_missing") return { ...issue, message: t.profileMissing(reference) };
+    if (issue.code === "model_profile_disabled") return { ...issue, message: t.profileDisabled(reference) };
+    const message =
+      issue.setting === "ai.vision_model_id"
+        ? t.noVision(reference)
+        : issue.setting === "ai.audio_model_id"
+          ? t.noTranscription(reference)
+          : t.transcriptionOnly(reference);
+    return { ...issue, message };
+  });
+
+  const errors: Record<string, string> = {};
+  for (const issue of described)
+    errors[issue.setting] = errors[issue.setting] ? `${errors[issue.setting]} ${issue.message}` : issue.message;
+  return { issues: described, errors };
+};
+
+export const aiSettingsNotSavedMessage = (locale?: string | null): string => catalog.resolve(locale ? [locale] : []).t.notSaved;
+export const checkAiSettingsMessages = () => catalog.check();

package/src/ai/settings.ts

@@ -185,6 +185,27 @@ export const parseAiModelProfiles = (rawJson: string): { profiles: AiModelProfil
   return { profiles };
 };
 
+export type AiModelReferenceSetting =
+  | "ai.default_model_id"
+  | "ai.background_model_id"
+  | "ai.workflow_model_id"
+  | "ai.vision_model_id"
+  | "ai.audio_model_id";
+
+/**
+ * One reason why a prospective AI configuration cannot be saved. Codes and
+ * profile ids are stable and locale-free; the admin route turns them into
+ * request-localized messages.
+ */
+export type AiSettingsIssue =
+  | { code: "model_required"; setting: AiModelReferenceSetting }
+  | {
+      code: "model_profile_missing" | "model_profile_disabled" | "model_profile_incompatible";
+      setting: AiModelReferenceSetting;
+      profileId: string;
+    }
+  | { code: "provider_credential_missing"; setting: "ai.model_profiles_json"; profileId: string };
+
 export const validateAiSettingsConfiguration = (input: {
   enabled: boolean;
   defaultModelId: string;
@@ -194,51 +215,41 @@ export const validateAiSettingsConfiguration = (input: {
   workflowModelId: string;
   profiles: readonly AiModelProfile[];
   credentialProfileIds: readonly string[];
-}): Record<string, string> => {
-  if (!input.enabled) return {};
-
-  const errors: Record<string, string> = {};
-  const enabledProfiles = input.profiles.filter((profile) => profile.enabled);
-  const defaultProfile = input.profiles.find((profile) => profile.id === input.defaultModelId);
-  if (!input.defaultModelId || !defaultProfile?.enabled || defaultProfile.capabilities.includes("transcription")) {
-    errors["ai.default_model_id"] = "Choose an enabled model profile.";
-  }
-
-  if (input.backgroundModelId) {
-    const backgroundProfile = input.profiles.find((profile) => profile.id === input.backgroundModelId);
-    if (!backgroundProfile?.enabled || backgroundProfile.capabilities.includes("transcription"))
-      errors["ai.background_model_id"] = "Choose an enabled chat model profile or use the platform default.";
-  }
-
-  if (input.visionModelId) {
-    const visionProfile = input.profiles.find((profile) => profile.id === input.visionModelId);
-    if (!visionProfile?.enabled || !visionProfile.capabilities.includes("vision")) {
-      errors["ai.vision_model_id"] = "Choose an enabled model profile with Vision support or disable the fallback.";
+}): AiSettingsIssue[] => {
+  if (!input.enabled) return [];
+
+  const issues: AiSettingsIssue[] = [];
+  const isChatModel = (profile: AiModelProfile) => !profile.capabilities.includes("transcription");
+  const checkReference = (
+    setting: AiModelReferenceSetting,
+    profileId: string | undefined,
+    fits: (profile: AiModelProfile) => boolean,
+    required = false,
+  ) => {
+    if (!profileId) {
+      if (required) issues.push({ code: "model_required", setting });
+      return;
     }
-  }
-
-  if (input.workflowModelId) {
-    const workflowProfile = input.profiles.find((profile) => profile.id === input.workflowModelId);
-    if (!workflowProfile?.enabled || workflowProfile.capabilities.includes("transcription"))
-      errors["ai.workflow_model_id"] = "Choose an enabled chat model profile or use the background model.";
-  }
+    const profile = input.profiles.find((item) => item.id === profileId);
+    if (!profile) issues.push({ code: "model_profile_missing", setting, profileId });
+    else if (!profile.enabled) issues.push({ code: "model_profile_disabled", setting, profileId });
+    else if (!fits(profile)) issues.push({ code: "model_profile_incompatible", setting, profileId });
+  };
 
-  if (input.audioModelId) {
-    const audioProfile = input.profiles.find((profile) => profile.id === input.audioModelId);
-    if (!audioProfile?.enabled || !audioProfile.capabilities.includes("transcription")) {
-      errors["ai.audio_model_id"] = "Choose an enabled audio transcription profile or disable audio transcription.";
-    }
-  }
+  checkReference("ai.default_model_id", input.defaultModelId, isChatModel, true);
+  checkReference("ai.background_model_id", input.backgroundModelId, isChatModel);
+  checkReference("ai.workflow_model_id", input.workflowModelId, isChatModel);
+  checkReference("ai.vision_model_id", input.visionModelId, (profile) => profile.capabilities.includes("vision"));
+  checkReference("ai.audio_model_id", input.audioModelId, (profile) => profile.capabilities.includes("transcription"));
 
   const configured = new Set(input.credentialProfileIds);
-  const missingCredentials = enabledProfiles.filter(
-    (profile) => providerRequiresCredential(profile.provider) && !configured.has(profile.id),
-  );
-  if (missingCredentials.length > 0) {
-    errors["ai.model_profiles_json"] = `Enter a provider API key for: ${missingCredentials.map((profile) => profile.label).join(", ")}.`;
+  for (const profile of input.profiles) {
+    if (profile.enabled && providerRequiresCredential(profile.provider) && !configured.has(profile.id)) {
+      issues.push({ code: "provider_credential_missing", setting: "ai.model_profiles_json", profileId: profile.id });
+    }
   }
 
-  return errors;
+  return issues;
 };
 
 export const planAiProfileCredentials = (input: {

package/src/api/admin-core-settings.ts

@@ -20,7 +20,8 @@ import {
   splitAiModelAccess,
 } from "../ai/model-access";
 import { parseAiModelProfiles, planAiProfileCredentials, validateAiSettingsConfiguration } from "../ai/settings";
-import { type AuthContext, auth, jsonResponse, requiresAdmin, v } from "../server";
+import { type AiSettingsIssueWithMessage, aiSettingsNotSavedMessage, describeAiSettingsIssues } from "../ai/settings-messages";
+import { type AuthContext, auth, getLocale, jsonResponse, requiresAdmin, v } from "../server";
 import { settingsDeleteLegacyKeys, settingsListLegacyKeys } from "../services";
 import { readAccountCategoryPolicy } from "../services/account-category-policy";
 import { audit } from "../services/audit";
@@ -97,6 +98,8 @@ const storeAiCredentials = async (
 
 type AiSettingsMutationPlan = {
   errors: FieldErrors;
+  /** Structured validation issues with stable codes; `errors` carries the same messages keyed by setting. */
+  issues?: AiSettingsIssueWithMessage[];
   keepCredentialProfileIds?: string[];
   modelProfileIds?: string[];
 };
@@ -111,6 +114,7 @@ const prepareAiSettingsMutation = async (
   updates: Record<string, unknown>,
   resets: readonly string[],
   aiSplit: ReturnType<typeof splitAiProfileCredentials>,
+  locale: string,
 ): Promise<AiSettingsMutationPlan> => {
   const keys = [...Object.keys(updates), ...resets];
   if (!keys.some((key) => AI_CONFIGURATION_KEYS.has(key))) return { errors: {} };
@@ -164,7 +168,7 @@ const prepareAiSettingsMutation = async (
     keepCredentialProfileIds = credentialPlan.keepCredentialProfileIds;
   }
 
-  const errors = validateAiSettingsConfiguration({
+  const issues = validateAiSettingsConfiguration({
     enabled: nextEnabled,
     defaultModelId: String(valueAfterMutation(AI_DEFAULT_MODEL_KEY, currentDefaultModelId ?? "", updates, resets)),
     backgroundModelId: String(valueAfterMutation(AI_BACKGROUND_MODEL_KEY, currentBackgroundModelId ?? "", updates, resets)),
@@ -174,8 +178,11 @@ const prepareAiSettingsMutation = async (
     profiles: nextParsed.profiles,
     credentialProfileIds: keepCredentialProfileIds ?? existingCredentialProfileIds,
   });
+  // Stored profiles come second so a profile that is being removed keeps its label.
+  const described = describeAiSettingsIssues(issues, { locale, profiles: [...nextParsed.profiles, ...currentParsed.profiles] });
   return {
-    errors,
+    errors: described.errors,
+    issues: described.issues,
     keepCredentialProfileIds,
     modelProfileIds: profilesUpdated || profilesReset ? nextParsed.profiles.map((profile) => profile.id) : undefined,
   };
@@ -405,13 +412,13 @@ const app = new Hono<AuthContext>()
 
     let aiPlan: AiSettingsMutationPlan;
     try {
-      aiPlan = await prepareAiSettingsMutation(validatedValues, resets, aiSplit);
+      aiPlan = await prepareAiSettingsMutation(validatedValues, resets, aiSplit, getLocale(c));
     } catch (error) {
       console.error("[settings] failed to validate the prospective AI configuration", error);
       return c.json({ message: "Failed to validate AI settings" }, 500);
     }
     if (Object.keys(aiPlan.errors).length > 0) {
-      return c.json({ message: "Invalid AI configuration", errors: aiPlan.errors }, 400);
+      return c.json({ message: aiSettingsNotSavedMessage(getLocale(c)), errors: aiPlan.errors, issues: aiPlan.issues ?? [] }, 400);
     }
 
     const fieldErrors: FieldErrors = {};
@@ -491,13 +498,13 @@ const app = new Hono<AuthContext>()
 
     let aiPlan: AiSettingsMutationPlan;
     try {
-      aiPlan = await prepareAiSettingsMutation({}, [key], null);
+      aiPlan = await prepareAiSettingsMutation({}, [key], null, getLocale(c));
     } catch (error) {
       console.error("[settings] failed to validate the prospective AI configuration", error);
       return c.json({ message: "Failed to validate AI settings" }, 500);
     }
     if (Object.keys(aiPlan.errors).length > 0) {
-      return c.json({ message: "Invalid AI configuration", errors: aiPlan.errors }, 400);
+      return c.json({ message: aiSettingsNotSavedMessage(getLocale(c)), errors: aiPlan.errors, issues: aiPlan.issues ?? [] }, 400);
     }
 
     try {

package/src/contracts/capability-compatibility.ts

@@ -0,0 +1,368 @@
+import { z } from "zod";
+import type { CapabilityActionManifest, CapabilityQueryManifest } from "./capabilities";
+
+/**
+ * A consumer-owned expectation of one provider capability: its kind, the input
+ * the consumer sends, and the minimum result data it reads.
+ */
+export type CapabilityContract = {
+  kind: "query" | "action";
+  idempotency?: "required";
+  input: z.ZodType;
+  data: z.ZodType;
+};
+
+export type CapabilityContractCandidate =
+  | { kind: "query"; operation: CapabilityQueryManifest }
+  | { kind: "action"; operation: CapabilityActionManifest };
+
+export type CapabilityContractIssue = {
+  /** `kind`, `idempotency`, and `stream` concern the operation; `input` and `data` its published schemas. */
+  code: "kind" | "idempotency" | "stream" | "input" | "data";
+  /** JSON path inside the input or data schema, `$` for the root. */
+  path: string;
+  message: string;
+};
+
+type Json = Record<string, unknown>;
+type Side = { schema: unknown; root: Json };
+type Mode = "input" | "data";
+type PathIssue = { path: string; message: string };
+const add = (issues: PathIssue[], path: string, message: string) => {
+  issues.push({ path, message });
+};
+
+const MAX_DEPTH = 32;
+const IGNORED_KEYWORDS = new Set(["$schema", "$id", "$defs", "definitions", "title", "description", "default", "examples", "readOnly"]);
+const SUPPORTED_KEYWORDS = new Set([
+  ...IGNORED_KEYWORDS,
+  "type",
+  "const",
+  "enum",
+  "anyOf",
+  "oneOf",
+  "allOf",
+  "$ref",
+  "properties",
+  "required",
+  "additionalProperties",
+  "items",
+  "minItems",
+  "maxItems",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "format",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+]);
+
+const isObject = (value: unknown): value is Json => value !== null && typeof value === "object" && !Array.isArray(value);
+
+const deref = (side: Side, depth: number): Side | null => {
+  let current = side.schema;
+  for (let hops = 0; isObject(current) && typeof current.$ref === "string"; hops++) {
+    if (hops > depth) return null;
+    const ref = current.$ref;
+    if (ref === "#") current = side.root;
+    else if (ref.startsWith("#/$defs/")) current = (side.root.$defs as Json | undefined)?.[ref.slice(8)];
+    else return null;
+  }
+  return { schema: current, root: side.root };
+};
+
+/** `true`, `{}`, and a schema with only annotations accept every value. */
+const acceptsAnything = (schema: unknown): boolean =>
+  schema === true || (isObject(schema) && Object.keys(schema).every((key) => IGNORED_KEYWORDS.has(key)));
+
+const typeSet = (schema: Json): Set<string> | null => {
+  if (typeof schema.type === "string") return new Set([schema.type]);
+  if (Array.isArray(schema.type)) return new Set(schema.type.filter((entry): entry is string => typeof entry === "string"));
+  return null;
+};
+
+const valuesOf = (schema: Json): unknown[] | null => {
+  if ("const" in schema) return [schema.const];
+  if (Array.isArray(schema.enum)) return schema.enum;
+  return null;
+};
+
+const jsonType = (value: unknown): string =>
+  value === null ? "null" : Array.isArray(value) ? "array" : Number.isInteger(value) ? "integer" : typeof value;
+
+const typeAllows = (allowed: Set<string>, type: string): boolean => allowed.has(type) || (type === "integer" && allowed.has("number"));
+
+const patternMatches = (pattern: string, value: string): boolean => {
+  try {
+    return new RegExp(pattern, "u").test(value);
+  } catch {
+    return false;
+  }
+};
+
+/** Checks one literal value against a provider or contract schema. Unknown keywords never pass. */
+const valueIssue = (value: unknown, sup: Side, depth: number): string | null => {
+  const resolved = deref(sup, depth);
+  if (!resolved) return "uses an unsupported reference";
+  const schema = resolved.schema;
+  if (acceptsAnything(schema)) return null;
+  if (!isObject(schema)) return "is not a JSON Schema object";
+  for (const keyword of ["anyOf", "oneOf"] as const) {
+    const branches = schema[keyword];
+    if (Array.isArray(branches) && !branches.some((branch) => valueIssue(value, { schema: branch, root: sup.root }, depth + 1) === null)) {
+      return `value ${JSON.stringify(value)} is not accepted`;
+    }
+  }
+  const values = valuesOf(schema);
+  if (values && !values.some((candidate) => JSON.stringify(candidate) === JSON.stringify(value))) {
+    return `value ${JSON.stringify(value)} is not accepted`;
+  }
+  const types = typeSet(schema);
+  if (types && !typeAllows(types, jsonType(value))) return `value ${JSON.stringify(value)} has the wrong type`;
+  if (typeof value === "string") {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) return "value is too short";
+    if (typeof schema.maxLength === "number" && value.length > schema.maxLength) return "value is too long";
+    if (typeof schema.pattern === "string" && !patternMatches(schema.pattern, value)) return "value does not match the pattern";
+  }
+  return null;
+};
+
+type Bound = { value: number; exclusive: boolean };
+const lowerBound = (schema: Json): Bound | null =>
+  typeof schema.exclusiveMinimum === "number"
+    ? { value: schema.exclusiveMinimum, exclusive: true }
+    : typeof schema.minimum === "number"
+      ? { value: schema.minimum, exclusive: false }
+      : null;
+const upperBound = (schema: Json): Bound | null =>
+  typeof schema.exclusiveMaximum === "number"
+    ? { value: schema.exclusiveMaximum, exclusive: true }
+    : typeof schema.maximum === "number"
+      ? { value: schema.maximum, exclusive: false }
+      : null;
+const withinLower = (sub: Bound | null, sup: Bound | null): boolean =>
+  !sup || (sub !== null && (sub.value > sup.value || (sub.value === sup.value && (sub.exclusive || !sup.exclusive))));
+const withinUpper = (sub: Bound | null, sup: Bound | null): boolean =>
+  !sup || (sub !== null && (sub.value < sup.value || (sub.value === sup.value && (sub.exclusive || !sup.exclusive))));
+
+const withinMin = (sub: unknown, sup: unknown): boolean => typeof sup !== "number" || (typeof sub === "number" && sub >= sup);
+const withinMax = (sub: unknown, sup: unknown): boolean => typeof sup !== "number" || (typeof sub === "number" && sub <= sup);
+
+/**
+ * Collects why `sub` may contain a value that `sup` rejects. The check is
+ * deliberately conservative: an unsupported keyword is an issue, never a pass.
+ */
+const subsetIssues = (sub: Side, sup: Side, path: string, mode: Mode, depth: number, issues: PathIssue[]): void => {
+  if (issues.length >= 5) return;
+  if (depth > MAX_DEPTH) {
+    add(issues, path, `schema is nested too deeply`);
+    return;
+  }
+  const subResolved = deref(sub, depth);
+  const supResolved = deref(sup, depth);
+  if (!subResolved || !supResolved) {
+    add(issues, path, `uses an unsupported reference`);
+    return;
+  }
+  const subSchema = subResolved.schema;
+  const supSchema = supResolved.schema;
+  if (acceptsAnything(supSchema)) return;
+  if (!isObject(supSchema)) {
+    if (supSchema === false) add(issues, path, `is not accepted`);
+    return;
+  }
+  if (acceptsAnything(subSchema)) {
+    add(issues, path, `is unconstrained but must match the contract`);
+    return;
+  }
+  if (!isObject(subSchema)) return;
+  const unsupported = [...Object.keys(subSchema), ...Object.keys(supSchema)].find((key) => !SUPPORTED_KEYWORDS.has(key));
+  if (unsupported) {
+    add(issues, path, `uses the unsupported keyword ${unsupported}`);
+    return;
+  }
+  const next = (schema: unknown, side: Side): Side => ({ schema, root: side.root });
+
+  // A union on the narrower side must fit branch by branch.
+  for (const keyword of ["anyOf", "oneOf"] as const) {
+    const branches = subSchema[keyword];
+    if (!Array.isArray(branches)) continue;
+    const { [keyword]: _branches, ...rest } = subSchema;
+    for (const branch of branches) {
+      const merged = isObject(branch) ? { ...rest, ...branch } : branch;
+      subsetIssues(next(merged, subResolved), supResolved, path, mode, depth + 1, issues);
+    }
+    return;
+  }
+  if (Array.isArray(subSchema.allOf)) {
+    // An intersection is narrower than each part; one fitting part is enough.
+    const { allOf, ...rest } = subSchema;
+    const fits = allOf.some((part) => {
+      const found: PathIssue[] = [];
+      subsetIssues(next(isObject(part) ? { ...rest, ...part } : part, subResolved), supResolved, path, mode, depth + 1, found);
+      return found.length === 0;
+    });
+    if (!fits) add(issues, path, `no part of the intersection matches the contract`);
+    return;
+  }
+  for (const keyword of ["anyOf", "oneOf"] as const) {
+    const branches = supSchema[keyword];
+    if (!Array.isArray(branches)) continue;
+    const { [keyword]: _branches, ...rest } = supSchema;
+    const fits = branches.some((branch) => {
+      const found: PathIssue[] = [];
+      subsetIssues(subResolved, next(isObject(branch) ? { ...rest, ...branch } : branch, supResolved), path, mode, depth + 1, found);
+      return found.length === 0;
+    });
+    if (!fits) add(issues, path, `does not match any allowed shape`);
+    return;
+  }
+  if (Array.isArray(supSchema.allOf)) {
+    const { allOf, ...rest } = supSchema;
+    for (const part of allOf)
+      subsetIssues(subResolved, next(isObject(part) ? { ...rest, ...part } : part, supResolved), path, mode, depth + 1, issues);
+    return;
+  }
+
+  const subValues = valuesOf(subSchema);
+  if (subValues) {
+    for (const value of subValues) {
+      const issue = valueIssue(value, supResolved, depth + 1);
+      if (issue) add(issues, path, `${issue}`);
+    }
+    return;
+  }
+  if (valuesOf(supSchema)) {
+    add(issues, path, `must be limited to the contract's allowed values`);
+    return;
+  }
+
+  const supTypes = typeSet(supSchema);
+  const subTypes = typeSet(subSchema);
+  if (supTypes) {
+    if (!subTypes) {
+      add(issues, path, `must declare a type`);
+      return;
+    }
+    const extra = [...subTypes].filter((type) => !typeAllows(supTypes, type));
+    if (extra.length > 0) {
+      add(issues, path, `allows ${extra.join(", ")} but the contract expects ${[...supTypes].join(", ")}`);
+      return;
+    }
+  }
+  const types = subTypes ?? new Set<string>();
+
+  // Providers own their identifier and text formats; input checks compare shape, not string syntax.
+  if (types.has("string") && mode === "data") {
+    if (typeof supSchema.format === "string" && subSchema.format !== supSchema.format) {
+      add(issues, path, `must use the ${supSchema.format} format`);
+    }
+    const formatCoversPattern = typeof supSchema.format === "string" && subSchema.format === supSchema.format;
+    if (typeof supSchema.pattern === "string" && !formatCoversPattern && subSchema.pattern !== supSchema.pattern) {
+      add(issues, path, `must use the contract pattern`);
+    }
+    if (!withinMin(subSchema.minLength, supSchema.minLength)) add(issues, path, `must be at least ${supSchema.minLength} characters`);
+    if (!withinMax(subSchema.maxLength, supSchema.maxLength)) add(issues, path, `must be at most ${supSchema.maxLength} characters`);
+  }
+  if (types.has("number") || types.has("integer")) {
+    if (!withinLower(lowerBound(subSchema), lowerBound(supSchema)) || !withinUpper(upperBound(subSchema), upperBound(supSchema))) {
+      add(issues, path, `allows numbers outside the contract range`);
+    }
+  }
+  if (types.has("array")) {
+    if (!withinMin(subSchema.minItems, supSchema.minItems)) add(issues, path, `must contain at least ${supSchema.minItems} items`);
+    if (!withinMax(subSchema.maxItems, supSchema.maxItems)) add(issues, path, `must contain at most ${supSchema.maxItems} items`);
+    if (supSchema.items !== undefined) {
+      subsetIssues(next(subSchema.items ?? true, subResolved), next(supSchema.items, supResolved), `${path}[]`, mode, depth + 1, issues);
+    }
+  }
+  if (types.has("object")) objectIssues(subSchema, subResolved, supSchema, supResolved, path, mode, depth, issues);
+};
+
+const objectIssues = (
+  subSchema: Json,
+  sub: Side,
+  supSchema: Json,
+  sup: Side,
+  path: string,
+  mode: Mode,
+  depth: number,
+  issues: PathIssue[],
+) => {
+  const subProperties = isObject(subSchema.properties) ? subSchema.properties : {};
+  const supProperties = isObject(supSchema.properties) ? supSchema.properties : {};
+  const subRequired = new Set(Array.isArray(subSchema.required) ? subSchema.required : []);
+  const supRequired = Array.isArray(supSchema.required) ? supSchema.required : [];
+  const subAdditional = subSchema.additionalProperties ?? true;
+  const supAdditional = supSchema.additionalProperties ?? true;
+  const field = (name: string) => `${path}.${name}`;
+
+  for (const name of supRequired) {
+    if (typeof name === "string" && !subRequired.has(name)) {
+      add(
+        issues,
+        field(name),
+        `${mode === "data" ? "must always be returned" : "is required by the provider but optional in the contract"}`,
+      );
+    }
+  }
+  for (const [name, schema] of Object.entries(subProperties)) {
+    if (name in supProperties) {
+      subsetIssues({ schema, root: sub.root }, { schema: supProperties[name], root: sup.root }, field(name), mode, depth + 1, issues);
+    } else if (supAdditional === false) {
+      add(issues, field(name), `is not accepted`);
+    } else {
+      subsetIssues({ schema, root: sub.root }, { schema: supAdditional, root: sup.root }, field(name), mode, depth + 1, issues);
+    }
+  }
+  if (subAdditional === false) return;
+  for (const [name, schema] of Object.entries(supProperties)) {
+    if (!(name in subProperties)) {
+      subsetIssues({ schema: subAdditional, root: sub.root }, { schema, root: sup.root }, field(name), mode, depth + 1, issues);
+    }
+  }
+  if (supAdditional === false) add(issues, path, `must not allow undeclared properties`);
+  else
+    subsetIssues(
+      { schema: subAdditional, root: sub.root },
+      { schema: supAdditional, root: sup.root },
+      `${path}.*`,
+      mode,
+      depth + 1,
+      issues,
+    );
+};
+
+const schemaIssues = (sub: Json, sup: Json, mode: Mode): PathIssue[] => {
+  const issues: PathIssue[] = [];
+  subsetIssues({ schema: sub, root: sub }, { schema: sup, root: sup }, "$", mode, 0, issues);
+  return issues;
+};
+
+/**
+ * Explains why a published capability cannot serve a consumer contract.
+ * An empty list means every contract input is accepted by the provider and
+ * every result the provider may return satisfies the contract data schema.
+ * Input checks compare shape, required fields, values, and numeric bounds;
+ * string syntax such as identifier patterns stays with the provider.
+ */
+export const capabilityContractIssues = (
+  contract: CapabilityContract,
+  candidate: CapabilityContractCandidate,
+): CapabilityContractIssue[] => {
+  if (candidate.kind !== contract.kind) {
+    return [{ code: "kind", path: "$", message: `Expected ${contract.kind === "query" ? "a Query" : "an Action"}` }];
+  }
+  const issues: CapabilityContractIssue[] = [];
+  if (candidate.operation.stream) issues.push({ code: "stream", path: "$", message: "Streaming capabilities are not supported" });
+  if (contract.idempotency === "required" && candidate.kind === "action" && candidate.operation.idempotency !== "required") {
+    issues.push({ code: "idempotency", path: "$", message: "The Action must require an idempotency key" });
+  }
+  const contractInput = z.toJSONSchema(contract.input, { io: "input" }) as Json;
+  const contractData = z.toJSONSchema(contract.data, { io: "output" }) as Json;
+  for (const issue of schemaIssues(contractInput, candidate.operation.inputSchema, "input")) issues.push({ code: "input", ...issue });
+  for (const issue of schemaIssues(candidate.operation.dataSchema, contractData, "data")) issues.push({ code: "data", ...issue });
+  return issues;
+};

package/src/contracts/contact-directory.ts

@@ -0,0 +1,165 @@
+import { z } from "zod";
+import { CapabilityQualifiedIdSchema, CapabilitySemanticLinkSchema } from "./capabilities";
+
+/**
+ * Provider-neutral contact-directory contract.
+ *
+ * A consumer such as Mail maps each function to one Query or Action of one
+ * provider application. Providers keep their own identifiers, permissions,
+ * and extra result fields; the schemas below are the minimum both sides share.
+ */
+
+// Identifiers are opaque provider strings; each provider owns their syntax and length.
+const ContactDirectoryIdSchema = z.string();
+const TimestampSchema = z.string().datetime({ offset: true });
+const NullableTextSchema = z.string().nullable();
+const CursorSchema = z.string().min(1).max(256);
+const EmailSchema = z.email().max(320);
+const LinksSchema = z.array(CapabilitySemanticLinkSchema).min(1).max(10).optional();
+
+const ContactDirectoryEmailSchema = z.object({ label: NullableTextSchema, email: z.email() }).loose();
+const ContactDirectoryPhoneSchema = z.object({ label: NullableTextSchema, phone: z.string().min(1) }).loose();
+
+const contactFacts = {
+  contactId: ContactDirectoryIdSchema,
+  bookId: ContactDirectoryIdSchema,
+  displayName: z.string().min(1),
+  companyName: NullableTextSchema,
+  jobTitle: NullableTextSchema,
+  contactPointsTruncated: z.boolean(),
+  links: LinksSchema,
+  updatedAt: TimestampSchema,
+};
+
+export const ContactDirectorySuggestInputSchema = z
+  .object({
+    query: z.string().min(2).max(500).describe("Text typed by the user, matched against names, organizations, and email addresses."),
+    cursor: CursorSchema.optional().describe("Opaque cursor returned by the previous page."),
+    limit: z.number().int().min(1).max(25).optional().describe("Maximum number of suggestions to return."),
+  })
+  .strict();
+
+export const ContactDirectorySuggestionSchema = z
+  .object({
+    ...contactFacts,
+    emails: z.array(ContactDirectoryEmailSchema).min(1).max(20),
+    phones: z.array(ContactDirectoryPhoneSchema).max(20),
+  })
+  .loose();
+export const ContactDirectorySuggestDataSchema = z.array(ContactDirectorySuggestionSchema).max(25);
+
+export const ContactDirectoryResolveInputSchema = z
+  .object({
+    emails: z.array(EmailSchema).min(1).max(100).describe("Normalized email addresses to resolve to every readable matching contact."),
+    contactIds: z
+      .array(ContactDirectoryIdSchema)
+      .max(20)
+      .optional()
+      .describe("Optional contact IDs returned by this provider that further restrict the matches."),
+    cursor: CursorSchema.optional().describe("Opaque cursor returned by the previous page."),
+    limit: z.number().int().min(1).max(50).optional().describe("Maximum number of exact contact matches to return."),
+  })
+  .strict();
+
+export const ContactDirectoryMatchSchema = z
+  .object({
+    ref: z.object({ type: CapabilityQualifiedIdSchema, id: ContactDirectoryIdSchema }).strict(),
+    ...contactFacts,
+    bookName: z.string().min(1),
+    matchedEmails: z.array(EmailSchema).min(1).max(100),
+    emails: z.array(ContactDirectoryEmailSchema).max(20),
+    phones: z.array(ContactDirectoryPhoneSchema).max(20),
+  })
+  .loose();
+export const ContactDirectoryResolveDataSchema = z
+  .object({
+    items: z.array(ContactDirectoryMatchSchema).max(50),
+    matchedEmails: z.array(EmailSchema).max(100),
+  })
+  .loose();
+
+export const ContactDirectoryReadInputSchema = z
+  .object({ id: ContactDirectoryIdSchema.describe("Contact ID returned by this provider.") })
+  .strict();
+
+export const ContactDirectoryContactSchema = z
+  .object({
+    id: ContactDirectoryIdSchema,
+    bookId: ContactDirectoryIdSchema,
+    displayName: z.string().min(1),
+    companyName: NullableTextSchema,
+    jobTitle: NullableTextSchema,
+    emails: z.array(ContactDirectoryEmailSchema).max(100),
+    phones: z.array(ContactDirectoryPhoneSchema).max(100),
+    updatedAt: TimestampSchema,
+  })
+  .loose();
+
+export const ContactDirectoryBookListInputSchema = z
+  .object({
+    query: z.string().max(500).optional().describe("Optional book name or description search."),
+    minimumPermission: z.literal("write").describe("Only books in which the caller can create contacts."),
+    cursor: CursorSchema.optional().describe("Opaque cursor returned by the previous page."),
+    limit: z.number().int().min(1).max(100).optional().describe("Maximum number of books to return."),
+  })
+  .strict();
+
+export const ContactDirectoryBookSchema = z
+  .object({ id: ContactDirectoryIdSchema, name: z.string().min(1), description: NullableTextSchema })
+  .loose();
+export const ContactDirectoryBookListDataSchema = z.array(ContactDirectoryBookSchema).max(100);
+
+const ContactPointLabelSchema = z.string().max(100).nullable().optional().describe("Optional label.");
+const ContactNameFieldSchema = z.string().max(200).nullable().optional();
+
+export const ContactDirectoryCreateInputSchema = z
+  .object({
+    bookId: ContactDirectoryIdSchema.describe("Writable book ID returned by the book list."),
+    label: ContactNameFieldSchema.describe("Optional display label."),
+    firstName: ContactNameFieldSchema.describe("Person first name."),
+    lastName: ContactNameFieldSchema.describe("Person last name."),
+    companyName: ContactNameFieldSchema.describe("Organization name."),
+    emails: z
+      .array(z.object({ label: ContactPointLabelSchema, email: EmailSchema.describe("Email address.") }).strict())
+      .max(20)
+      .optional()
+      .describe("Email addresses."),
+    phones: z
+      .array(z.object({ label: ContactPointLabelSchema, phone: z.string().min(1).max(100).describe("Phone number.") }).strict())
+      .max(20)
+      .optional()
+      .describe("Phone numbers."),
+  })
+  .strict();
+export const ContactDirectoryCreateDataSchema = z.object({ contact: ContactDirectoryContactSchema }).loose();
+
+/**
+ * The five contact-directory functions. `kind` and `idempotency` are part of
+ * the contract: a provider capability must match them to be selectable.
+ */
+export const contactDirectory = {
+  suggest: { kind: "query", input: ContactDirectorySuggestInputSchema, data: ContactDirectorySuggestDataSchema },
+  resolve: { kind: "query", input: ContactDirectoryResolveInputSchema, data: ContactDirectoryResolveDataSchema },
+  read: { kind: "query", input: ContactDirectoryReadInputSchema, data: ContactDirectoryContactSchema },
+  listWritableBooks: { kind: "query", input: ContactDirectoryBookListInputSchema, data: ContactDirectoryBookListDataSchema },
+  create: {
+    kind: "action",
+    idempotency: "required",
+    input: ContactDirectoryCreateInputSchema,
+    data: ContactDirectoryCreateDataSchema,
+  },
+} as const;
+
+export type ContactDirectoryFunction = keyof typeof contactDirectory;
+export const CONTACT_DIRECTORY_FUNCTIONS = [
+  "suggest",
+  "resolve",
+  "read",
+  "listWritableBooks",
+  "create",
+] as const satisfies readonly ContactDirectoryFunction[];
+
+export type ContactDirectorySuggestion = z.output<typeof ContactDirectorySuggestionSchema>;
+export type ContactDirectoryMatch = z.output<typeof ContactDirectoryMatchSchema>;
+export type ContactDirectoryContact = z.output<typeof ContactDirectoryContactSchema>;
+export type ContactDirectoryBook = z.output<typeof ContactDirectoryBookSchema>;

package/src/contracts/index.ts

@@ -3,7 +3,9 @@ export * from "./announcements";
 export * from "./app";
 export * from "./app-approval";
 export * from "./capabilities";
+export * from "./capability-compatibility";
 export * from "./commands";
+export * from "./contact-directory";
 export * from "./notification-types";
 export * from "./posix";
 export * from "./profile";

package/src/services/document-extraction.ts

@@ -106,6 +106,8 @@ const mapConversionError = (error: unknown, format: DocumentFormat): DocumentExt
     case "malformed":
     case "missingPart":
       return new DocumentExtractionError("malformed", "The document is malformed or incomplete.");
+    case "needsOcr":
+      return new DocumentExtractionError("ocr_required", "The PDF has no readable text and requires OCR.");
     case "unsupported":
       return format === "pdf"
         ? new DocumentExtractionError("ocr_required", "The PDF has no readable text and requires OCR.")

package/src/services/webauthn.ts

@@ -1,7 +1,6 @@
 import { err, fail, ok, type Result } from "@k2b/stdlib";
 import {
   type AuthenticationResponseJSON,
-  type AuthenticatorTransportFuture,
   generateAuthenticationOptions,
   generateRegistrationOptions,
   type PublicKeyCredentialCreationOptionsJSON,
@@ -137,7 +136,7 @@ const toCredential = (row: DbPasskeyRow): WebAuthnCredential => ({
   id: row.credential_id,
   publicKey: new Uint8Array(row.public_key) as WebAuthnCredential["publicKey"],
   counter: Number(row.counter),
-  transports: (row.transports ?? []) as AuthenticatorTransportFuture[],
+  transports: row.transports ?? [],
 });
 
 const isExpired = (date: Date | null): boolean => Boolean(date && date.getTime() <= Date.now());
@@ -176,7 +175,7 @@ export const beginRegistration = async (params: { user: User }): Promise<Result<
     },
     excludeCredentials: existing.map((credential) => ({
       id: credential.credentialId,
-      transports: credential.transports as AuthenticatorTransportFuture[],
+      transports: credential.transports,
     })),
   });