jev-layer 0.1.0

package/src/receipts.mjs

@@ -0,0 +1,226 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { stableJson } from "./contract.mjs";
+import { sanitizeContext } from "./context-filter.mjs";
+
+const MAX_RESULT_BYTES = 8_000;
+
+export function replayCasePath(filePath = process.env.JEV_REPLAY_CASES) {
+  return resolve(filePath || ".jev/replay/cases.jsonl");
+}
+
+export function buildRoutingCase({ request, decision, recordedAt = new Date().toISOString() }) {
+  const correlationId = decision.correlation_id ?? decision.receipt?.correlation_id ?? decision.receipt?.request_id;
+  if (!correlationId) throw new TypeError("decision correlation_id is required");
+  return {
+    record_type: "routing_case",
+    schema_version: 1,
+    case_id: correlationId,
+    correlation_id: correlationId,
+    recorded_at: recordedAt,
+    harness: request.harness ?? "unknown",
+    request: replayRequest(request),
+    decision: decisionSummary(decision),
+  };
+}
+
+export function buildExecutionReceipt({ request, decision, host, recordedAt = new Date().toISOString() }) {
+  const correlationId = decision.correlation_id ?? decision.receipt?.correlation_id ?? decision.receipt?.request_id;
+  if (!correlationId) throw new TypeError("decision correlation_id is required");
+  if (!host || typeof host !== "object") throw new TypeError("host execution is required");
+  const exitStatus = Number.isInteger(host.exit_status) ? host.exit_status : null;
+  const status = typeof host.status === "string"
+    ? host.status
+    : exitStatus === null || exitStatus === 0 ? "completed" : "failed";
+  return {
+    record_type: "execution_receipt",
+    schema_version: 1,
+    receipt_id: `${correlationId}:execution`,
+    correlation_id: correlationId,
+    recorded_at: recordedAt,
+    harness: host.harness ?? request.harness ?? "unknown",
+    candidates: decision.candidates ?? [],
+    selected: decision.selected ?? null,
+    confidence: decision.confidence ?? null,
+    probabilities: decision.probabilities ?? {},
+    fallback: decision.fallback ?? null,
+    jev: {
+      correlation_id: correlationId,
+      request_id: decision.receipt?.request_id ?? correlationId,
+      provider: decision.receipt?.provider ?? null,
+      latency_ms: decision.receipt?.latency_ms ?? null,
+      cost_usd: decision.receipt?.cost_usd ?? decision.raw_jev?.usage?.cost ?? null,
+      status: decision.status ?? null,
+    },
+    host: {
+      capability_id: host.capability_id ?? decision.selected ?? null,
+      status,
+      result: boundedValue(host.result ?? host.host_result ?? null),
+      error: boundedValue(host.error ?? null),
+      exit_status: exitStatus,
+      duration_ms: finiteNumber(host.duration_ms),
+      started_at: host.started_at ?? null,
+      completed_at: host.completed_at ?? recordedAt,
+      browser: boundedValue(host.browser ?? null),
+    },
+  };
+}
+
+export async function appendRoutingCase({ path, request, decision }) {
+  const record = buildRoutingCase({ request, decision });
+  await appendRecord(path, record);
+  return { record, path: replayCasePath(path) };
+}
+
+export async function appendExecutionReceipt({ path, request, decision, host }) {
+  const record = buildExecutionReceipt({ request, decision, host });
+  await appendRecord(path, record);
+  return { record, path: replayCasePath(path) };
+}
+
+export function buildSupervisionReceipt({ request, result, recordedAt = new Date().toISOString() }) {
+  const correlationId = result.receipt?.correlation_id;
+  if (!correlationId) throw new TypeError("supervision result correlation_id is required");
+  return {
+    record_type: "supervision_case",
+    schema_version: 1,
+    case_id: correlationId,
+    correlation_id: correlationId,
+    recorded_at: recordedAt,
+    harness: request.harness ?? "unknown",
+    request: {
+      schema_version: request.schema_version ?? 1,
+      harness: request.harness ?? "unknown",
+      intent: request.intent,
+      context: sanitizeContext(request.context ?? {}),
+      actor_permissions: request.actor_permissions ?? [],
+      policy: request.policy ?? {},
+    },
+    supervision: {
+      status: result.status ?? null,
+      action: result.action ?? "continue",
+      reason: result.reason ?? null,
+      assessment: result.assessment ?? null,
+      policy: result.policy ?? null,
+      jev: {
+        provider: result.receipt.provider ?? null,
+        latency_ms: result.receipt.latency_ms ?? null,
+        cost_usd: result.receipt.cost_usd ?? null,
+        dimensions: result.receipt.dimensions ?? null,
+      },
+    },
+  };
+}
+
+export async function appendSupervisionReceipt({ path, request, result }) {
+  const record = buildSupervisionReceipt({ request, result });
+  await appendRecord(path, record);
+  return { record, path: replayCasePath(path) };
+}
+
+export async function readRoutingCases(path) {
+  const resolved = replayCasePath(path);
+  let text;
+  try {
+    text = await readFile(resolved, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  return text.split(/\r?\n/).filter(Boolean).flatMap((line, index) => {
+    try {
+      const record = JSON.parse(line);
+      return record.record_type === "routing_case" ? [{ ...record, source_line: index + 1 }] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+
+export async function readSupervisionCases(path) {
+  const resolved = replayCasePath(path);
+  let text;
+  try {
+    text = await readFile(resolved, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  return text.split(/\r?\n/).filter(Boolean).flatMap((line, index) => {
+    try {
+      const record = JSON.parse(line);
+      return record.record_type === "supervision_case" ? [{ ...record, source_line: index + 1 }] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function replayRequest(request) {
+  return {
+    schema_version: request.schema_version ?? 1,
+    harness: request.harness ?? "unknown",
+    intent: request.intent,
+    context: sanitizeContext(request.context ?? {}),
+    actor: request.actor,
+    actor_permissions: Array.isArray(request.actor_permissions) ? request.actor_permissions.filter((value) => typeof value === "string") : undefined,
+    policy: request.policy && typeof request.policy === "object" ? request.policy : {},
+    capabilities: Array.isArray(request.capabilities) ? request.capabilities.map(replayCapability) : [],
+  };
+}
+
+function replayCapability(capability) {
+  const risk = capability.risk?.level ?? capability.risk ?? "medium";
+  return {
+    id: capability.id,
+    kind: capability.kind ?? capability.type ?? "tool",
+    name: capability.name,
+    description: capability.description,
+    permissions: Array.isArray(capability.permissions) ? capability.permissions.filter((value) => typeof value === "string") : [],
+    risk,
+    available: capability.available,
+    availability: capability.availability,
+    source: typeof capability.source === "string" ? capability.source : null,
+    verified: capability.verified === true,
+    metadata: capability.metadata && typeof capability.metadata === "object" ? capability.metadata : {},
+    policy: capability.policy,
+  };
+}
+
+function decisionSummary(decision) {
+  return {
+    status: decision.status ?? null,
+    selected: decision.selected ?? null,
+    confidence: decision.confidence ?? null,
+    probabilities: decision.probabilities ?? {},
+    fallback: decision.fallback ?? null,
+    candidates: decision.candidates ?? [],
+    receipt: {
+      correlation_id: decision.receipt?.correlation_id ?? decision.correlation_id ?? null,
+      request_id: decision.receipt?.request_id ?? null,
+      provider: decision.receipt?.provider ?? null,
+      latency_ms: decision.receipt?.latency_ms ?? null,
+      cost_usd: decision.receipt?.cost_usd ?? decision.raw_jev?.usage?.cost ?? null,
+      candidate_count: decision.receipt?.candidate_count ?? null,
+      context_bytes: decision.receipt?.context_bytes ?? null,
+    },
+  };
+}
+
+async function appendRecord(path, record) {
+  const resolved = replayCasePath(path);
+  await mkdir(dirname(resolved), { recursive: true });
+  await appendFile(resolved, `${stableJson(record)}\n`, "utf8");
+}
+
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+function boundedValue(value) {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") return value.length > MAX_RESULT_BYTES ? `${value.slice(0, MAX_RESULT_BYTES)}…` : value;
+  const sanitized = sanitizeContext(value);
+  const encoded = stableJson(sanitized);
+  return encoded.length > MAX_RESULT_BYTES ? `${encoded.slice(0, MAX_RESULT_BYTES)}…` : sanitized;
+}

package/src/registry.mjs

@@ -0,0 +1,109 @@
+import { CAPABILITY_KINDS, RISK_ORDER } from "./contract.mjs";
+
+const KIND_ALIASES = Object.freeze({ mcp_tool: "mcp" });
+
+export const DEFAULT_POLICY = Object.freeze({
+  min_confidence: 0.62,
+  max_risk: "high",
+  confirmation_risk_levels: ["medium", "high"],
+});
+
+export function normalizeCapability(raw, index = 0) {
+  if (!raw || typeof raw !== "object") throw new TypeError(`capabilities[${index}] must be an object`);
+  if (typeof raw.id !== "string" || raw.id.trim() === "") throw new TypeError(`capabilities[${index}].id is required`);
+  if (typeof raw.name !== "string" || raw.name.trim() === "") throw new TypeError(`capabilities[${index}].name is required`);
+  if (typeof raw.description !== "string" || raw.description.trim() === "") throw new TypeError(`capabilities[${index}].description is required`);
+
+  const rawKind = raw.kind ?? raw.type ?? raw.execution?.mode ?? "tool";
+  const kind = KIND_ALIASES[rawKind] ?? rawKind;
+  if (!CAPABILITY_KINDS.has(kind)) throw new TypeError(`capabilities[${index}].kind is unsupported: ${rawKind}`);
+
+  const risk = raw.risk?.level ?? raw.risk ?? "medium";
+  if (!(risk in RISK_ORDER)) throw new TypeError(`capabilities[${index}].risk is unsupported: ${risk}`);
+
+  return {
+    id: raw.id.trim(),
+    kind,
+    name: raw.name.trim(),
+    description: raw.description.trim(),
+    permissions: Array.isArray(raw.permissions) ? raw.permissions.filter((value) => typeof value === "string") : [],
+    risk,
+    available: raw.available !== false && raw.availability?.available !== false,
+    availability_reason: raw.availability?.reason ?? null,
+    source: typeof raw.source === "string" ? raw.source : null,
+    verified: raw.verified === true,
+    metadata: normalizeMetadata(raw.metadata ?? raw.discovery),
+    execution: {
+      mode: "host",
+      target: typeof raw.execution?.target === "string" ? raw.execution.target : undefined,
+    },
+    requires_confirmation: Boolean(raw.policy?.requires_confirmation) || risk !== "low",
+  };
+}
+
+export function normalizeCapabilities(rawCapabilities) {
+  const seen = new Set();
+  return rawCapabilities.map((raw, index) => {
+    const capability = normalizeCapability(raw, index);
+    if (seen.has(capability.id)) throw new TypeError(`duplicate capability id: ${capability.id}`);
+    seen.add(capability.id);
+    return capability;
+  });
+}
+
+export function filterCapabilities(capabilities, request, policy = {}) {
+  const effective = { ...DEFAULT_POLICY, ...policy };
+  const maxRisk = effective.max_risk ?? "high";
+  const actorPermissions = Array.isArray(request.actor_permissions) ? new Set(request.actor_permissions) : null;
+  const assessments = capabilities.map((capability) => {
+    let reason = null;
+    if (!capability.available) reason = capability.availability_reason || "capability unavailable";
+    else if (RISK_ORDER[capability.risk] > RISK_ORDER[maxRisk]) reason = `risk ${capability.risk} exceeds policy maximum ${maxRisk}`;
+    else if (actorPermissions && capability.permissions.some((permission) => !actorPermissions.has(permission))) reason = "actor lacks required capability permissions";
+    return { capability, filtered: Boolean(reason), filter_reason: reason };
+  });
+  return {
+    policy: effective,
+    assessments,
+    eligible: assessments.filter((assessment) => !assessment.filtered).map((assessment) => assessment.capability),
+  };
+}
+export function decisionCandidates(assessments, probabilities = {}, confidence = null) {
+  return assessments.map(({ capability, filtered, filter_reason }) => ({
+    id: capability.id,
+    kind: capability.kind,
+    name: capability.name,
+    risk: capability.risk,
+    available: capability.available,
+    filtered,
+    filter_reason,
+    probability: typeof probabilities[capability.id] === "number" ? probabilities[capability.id] : null,
+    confidence: confidence ?? null,
+    requires_confirmation: capability.requires_confirmation,
+    source: capability.source,
+    verified: capability.verified,
+    metadata: capability.metadata,
+  }));
+}
+
+export function deterministicCandidate(capabilities, policy = {}) {
+  let eligible = capabilities;
+  const requestedId = typeof policy.deterministic_capability_id === "string" ? policy.deterministic_capability_id : null;
+  if (requestedId) eligible = eligible.filter((capability) => capability.id === requestedId);
+  if (typeof policy.prefer_kind === "string") eligible = eligible.filter((capability) => capability.kind === policy.prefer_kind);
+  if (typeof policy.prefer_source === "string") eligible = eligible.filter((capability) => capability.source === policy.prefer_source);
+  if (policy.prefer_verified === true) eligible = eligible.filter((capability) => capability.verified);
+  if (eligible.length !== 1) return null;
+  return {
+    capability: eligible[0],
+    reason: requestedId ? "explicit capability policy" : "one capability remains after deterministic policy",
+  };
+}
+
+function normalizeMetadata(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const allowed = ["skill", "mcp", "cli", "dsh", "subagent", "model", "manifest", "source_ref"];
+  return Object.fromEntries(allowed
+    .filter((key) => typeof value[key] === "string" || typeof value[key] === "boolean")
+    .map((key) => [key, value[key]]));
+}

package/src/relevance-filter.mjs

@@ -0,0 +1,99 @@
+const MODES = new Set(["shadow", "conservative"]);
+const SIGNALS = [
+  /(?:^|[\s"'`])(?:\/[\w.\-~]+|~\/[^\s"'`]+|[A-Za-z]:\\[^\s"'`]+)/u,
+  /\b(?:error|exception|traceback|failed|failure|exit\s+status|stderr)\b/i,
+  /`[^`\n]+`/u,
+  /(?:^|\n)\s*(?:[$#])\s*[A-Za-z0-9_.-]+/u,
+  /\b(?:must|required|requirement|acceptance|should|need\s+to)\b/i,
+];
+const LIST_KEYS = new Set(["messages", "events", "logs", "tool_results", "history", "transcript"]);
+
+export function normalizeRelevanceMode(mode) {
+  if (mode === true) return "shadow";
+  if (typeof mode !== "string") return null;
+  const normalized = mode.trim().toLowerCase();
+  return MODES.has(normalized) ? normalized : null;
+}
+
+export function filterContext(context, { mode = "shadow", recent = 8 } = {}) {
+  const normalizedMode = normalizeRelevanceMode(mode);
+  if (!normalizedMode) return { context, report: disabledReport() };
+  const source = context && typeof context === "object" ? context : {};
+  const report = {
+    mode: normalizedMode,
+    changed: false,
+    considered: 0,
+    kept: 0,
+    dropped: 0,
+    pinned: 0,
+    pinned_reasons: [],
+  };
+  if (normalizedMode === "shadow") {
+    inspectValue(source, report);
+    return { context: source, report };
+  }
+
+  const output = Array.isArray(source) ? source.slice() : { ...source };
+  for (const [key, value] of Object.entries(source)) {
+    if (!LIST_KEYS.has(key) || !Array.isArray(value)) continue;
+    const filtered = filterList(value, normalizedMode, recent, report);
+    output[key] = filtered;
+  }
+  if (report.dropped > 0) {
+    report.changed = true;
+    output._jev_relevance = {
+      mode: normalizedMode,
+      dropped: report.dropped,
+      pinned: report.pinned,
+    };
+  }
+  return { context: output, report };
+}
+
+export function isPinnedEvidence(value) {
+  const text = typeof value === "string" ? value : JSON.stringify(value ?? "");
+  const reasons = [];
+  if (SIGNALS[0].test(text)) reasons.push("path");
+  if (SIGNALS[1].test(text)) reasons.push("error");
+  if (SIGNALS[2].test(text) || SIGNALS[3].test(text)) reasons.push("command");
+  if (SIGNALS[4].test(text)) reasons.push("requirement");
+  return { pinned: reasons.length > 0, reasons };
+}
+
+function filterList(items, mode, recent, report) {
+  const keepFrom = Math.max(0, items.length - Math.max(0, recent));
+  return items.filter((item, index) => {
+    report.considered += 1;
+    const evidence = isPinnedEvidence(item);
+    const keep = evidence.pinned || index >= keepFrom || mode === "conservative" && index === items.length - 1;
+    if (evidence.pinned) {
+      report.pinned += 1;
+      report.pinned_reasons.push(...evidence.reasons);
+    }
+    if (keep) report.kept += 1;
+    else report.dropped += 1;
+    return keep;
+  });
+}
+
+function inspectValue(value, report) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      report.considered += 1;
+      const evidence = isPinnedEvidence(item);
+      if (evidence.pinned) {
+        report.pinned += 1;
+        report.pinned_reasons.push(...evidence.reasons);
+      }
+      inspectValue(item, report);
+    }
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const child of Object.values(value)) inspectValue(child, report);
+  }
+}
+
+function disabledReport() {
+  return { mode: null, changed: false, considered: 0, kept: 0, dropped: 0, pinned: 0, pinned_reasons: [] };
+}

package/src/route.mjs

@@ -0,0 +1,221 @@
+import { byteLength, decisionEnvelope, normalizeRequest } from "./contract.mjs";
+import { projectState } from "./context-filter.mjs";
+import { discoverCapabilities } from "./discovery.mjs";
+import { decisionCandidates, DEFAULT_POLICY, deterministicCandidate, filterCapabilities, normalizeCapabilities } from "./registry.mjs";
+import { DemoProvider } from "./providers/demo.mjs";
+import { OpenRouterDecisionsProvider, TypeSafeProvider } from "./providers/typesafe.mjs";
+
+export async function routeRequest(input, options = {}) {
+  const discovered = options.discovery ? discoverCapabilities(options.discovery) : [];
+  const request = normalizeRequest(discovered.length ? { ...input, capabilities: [...(Array.isArray(input?.capabilities) ? input.capabilities : []), ...discovered] } : input);
+  if (options.engine === "jevrouter") return routeViaJevRouter(request, options);
+
+  const started = performance.now();
+  const effectivePolicy = { ...DEFAULT_POLICY, ...request.policy, ...(options.policy ?? {}) };
+  const capabilities = normalizeCapabilities(request.capabilities);
+  const { policy, assessments, eligible } = filterCapabilities(capabilities, request, effectivePolicy);
+  const projection = projectState(request, eligible, options.maxContextBytes ?? 6_000, { mode: options.contextFilterMode });
+  const provider = resolveProvider(options.provider ?? "demo", options);
+  const base = {
+    provider: provider.name,
+    candidateCount: eligible.length,
+    contextBytes: projection.context_bytes,
+    started,
+  };
+
+  if (process.env.JEV_LAYER_ENABLED === "0") {
+    return fallback(base, assessments, "disabled", "Jev layer disabled by JEV_LAYER_ENABLED=0", projection.state);
+  }
+  if (eligible.length === 0) {
+    return decisionEnvelope({
+      status: "no_decision",
+      reason: "no capability passed availability, risk, and permission policy",
+      provider: provider.name,
+      latencyMs: elapsed(started),
+      candidateCount: 0,
+      contextBytes: projection.context_bytes,
+      candidates: decisionCandidates(assessments),
+    });
+  }
+  const deterministic = policy.deterministic === true
+    ? deterministicCandidate(eligible, policy)
+    : null;
+  if (deterministic) {
+    const selected = deterministic.capability;
+    const probabilities = Object.fromEntries(eligible.map((candidate) => [candidate.id, candidate.id === selected.id ? 1 : 0]));
+    const candidates = decisionCandidates(assessments, probabilities, 1);
+    const requiresConfirmation = policy.confirmation_risk_levels.includes(selected.risk) || selected.requires_confirmation;
+    return decisionEnvelope({
+      status: requiresConfirmation ? "needs_confirmation" : "selected",
+      reason: deterministic.reason,
+      provider: `${provider.name}:deterministic`,
+      latencyMs: elapsed(started),
+      candidateCount: eligible.length,
+      contextBytes: projection.context_bytes,
+      candidates,
+      selected: selected.id,
+      probabilities,
+      confidence: 1,
+    });
+  }
+
+  let raw;
+  try {
+    raw = await provider.decide({ state: projection.state, candidates: eligible });
+  } catch (error) {
+    return fallback(base, assessments, "provider_error", error instanceof Error ? error.message : String(error), projection.state);
+  }
+
+  let answer;
+  try {
+    answer = readChoiceAnswer(raw);
+  } catch (error) {
+    return fallback(base, assessments, "malformed_response", error instanceof Error ? error.message : String(error), projection.state, raw);
+  }
+
+  const selected = eligible.find((candidate) => candidate.id === answer.choice);
+  const candidates = decisionCandidates(assessments, answer.probabilities, answer.confidence);
+  if (!selected) {
+    return decisionEnvelope({
+      status: "fallback",
+      reason: `provider selected unknown or filtered capability: ${answer.choice}`,
+      provider: provider.name,
+      latencyMs: elapsed(started),
+      candidateCount: eligible.length,
+      contextBytes: projection.context_bytes,
+      candidates,
+      probabilities: answer.probabilities,
+      confidence: answer.confidence,
+      rawJev: raw,
+      fallback: { type: "invalid_selection", reason: "selection is not in the eligible candidate set" },
+    });
+  }
+  if (answer.confidence < policy.min_confidence) {
+    return decisionEnvelope({
+      status: "fallback",
+      reason: `confidence ${answer.confidence.toFixed(3)} is below policy minimum ${policy.min_confidence.toFixed(3)}`,
+      provider: provider.name,
+      latencyMs: elapsed(started),
+      candidateCount: eligible.length,
+      contextBytes: projection.context_bytes,
+      candidates,
+      selected: selected.id,
+      probabilities: answer.probabilities,
+      confidence: answer.confidence,
+      rawJev: raw,
+      fallback: { type: "low_confidence", reason: "host must continue with normal planning" },
+    });
+  }
+
+  const requiresConfirmation = policy.confirmation_risk_levels.includes(selected.risk) || selected.requires_confirmation;
+  return decisionEnvelope({
+    status: requiresConfirmation ? "needs_confirmation" : "selected",
+    reason: requiresConfirmation ? "selected capability requires host confirmation" : "selected by bounded Jev decision",
+    provider: provider.name,
+    latencyMs: elapsed(started),
+    candidateCount: eligible.length,
+    contextBytes: projection.context_bytes,
+    candidates,
+    selected: selected.id,
+    probabilities: answer.probabilities,
+    confidence: answer.confidence,
+    rawJev: raw,
+  });
+}
+
+function resolveProvider(provider, options) {
+  if (provider && typeof provider === "object" && typeof provider.decide === "function") return provider;
+  if (provider === "demo") return new DemoProvider();
+  if (provider === "openrouter") return new OpenRouterDecisionsProvider(options.openrouter);
+  throw new Error(`unsupported provider: ${provider}`);
+}
+
+function readChoiceAnswer(raw) {
+  const answers = raw?.answers;
+  if (!answers || typeof answers !== "object") throw new Error("response has no answers object");
+  const answer = answers.tool ?? Object.values(answers).find((value) => value?.type === "choice");
+  if (!answer || answer.type !== "choice" || typeof answer.choice !== "string" || !answer.probabilities || typeof answer.probabilities !== "object") {
+    throw new Error("response does not contain a valid Choice answer");
+  }
+  const probabilities = Object.fromEntries(Object.entries(answer.probabilities).map(([id, value]) => {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) throw new Error(`invalid probability for ${id}`);
+    return [id, value];
+  }));
+  const confidence = typeof answer.confidence === "number" ? answer.confidence : Math.max(...Object.values(probabilities), 0);
+  if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) throw new Error("invalid confidence");
+  return { choice: answer.choice, probabilities, confidence };
+}
+
+function fallback(base, assessments, type, reason, state, rawJev = null) {
+  return decisionEnvelope({
+    status: "fallback",
+    reason,
+    provider: base.provider,
+    latencyMs: elapsed(base.started),
+    candidateCount: base.candidateCount,
+    contextBytes: byteLength(state),
+    candidates: decisionCandidates(assessments),
+    rawJev,
+    fallback: { type, reason },
+  });
+}
+
+function elapsed(started) {
+  return Number((performance.now() - started).toFixed(3));
+}
+
+async function routeViaJevRouter(request, options) {
+  const started = performance.now();
+  const capabilities = normalizeCapabilities(request.capabilities);
+  const { assessments, eligible } = filterCapabilities(capabilities, request, { ...DEFAULT_POLICY, ...request.policy, ...(options.policy ?? {}) });
+  const projection = projectState(request, eligible, options.maxContextBytes ?? 6_000, { mode: options.contextFilterMode });
+  if (eligible.length === 0) return decisionEnvelope({ status: "no_decision", reason: "no eligible capability", provider: "jevrouter", latencyMs: elapsed(started), candidateCount: 0, contextBytes: projection.context_bytes, candidates: decisionCandidates(assessments) });
+
+  let module;
+  try {
+    module = await import("jevrouter");
+  } catch (error) {
+    return fallback({ provider: "jevrouter", candidateCount: eligible.length, contextBytes: projection.context_bytes, started }, assessments, "dependency_error", error instanceof Error ? error.message : String(error), projection.state);
+  }
+  try {
+    const result = await module.route({
+      request: request.intent,
+      context: projection.state.context,
+      candidates: eligible.map(toJevRouterCapability),
+    }, {
+      provider: options.innerProvider ?? process.env.JEVROUTER_PROVIDER ?? "demo",
+      policy: options.policy,
+    });
+    const selected = result.decision?.selected ?? null;
+    const raw = result.raw_jev ?? null;
+    const candidates = decisionCandidates(assessments, Object.fromEntries((result.decision?.candidates ?? []).map((candidate) => [candidate.id, candidate.jev_probability ?? 0])), null);
+    return decisionEnvelope({
+      status: result.status === "selected" ? "selected" : result.status === "needs_confirmation" ? "needs_confirmation" : "fallback",
+      selected,
+      reason: result.fallback?.reason ?? "selected by JevRouter",
+      provider: `jevrouter:${options.innerProvider ?? process.env.JEVROUTER_PROVIDER ?? "demo"}`,
+      latencyMs: elapsed(started),
+      candidateCount: eligible.length,
+      contextBytes: projection.context_bytes,
+      candidates,
+      rawJev: raw,
+      fallback: result.fallback?.type ? { type: result.fallback.type, reason: result.fallback.reason } : null,
+    });
+  } catch (error) {
+    return fallback({ provider: "jevrouter", candidateCount: eligible.length, contextBytes: projection.context_bytes, started }, assessments, "provider_error", error instanceof Error ? error.message : String(error), projection.state);
+  }
+}
+
+function toJevRouterCapability(capability) {
+  return {
+    id: capability.id,
+    name: capability.name,
+    type: capability.kind === "mcp" ? "mcp_tool" : capability.kind,
+    description: capability.description,
+    permissions: capability.permissions,
+    risk: { level: capability.risk },
+    availability: { available: capability.available },
+    execution: { mode: capability.kind === "mcp" ? "mcp" : capability.kind, target: capability.execution.target },
+    policy: { requires_confirmation: capability.requires_confirmation },
+  };
+}