@openbkn/bkn-sdk 0.1.1-alpha.9 → 0.1.2

package/dist/{chunk-BFE4SU3V.js → chunk-LH3ONZGQ.js}

@@ -9,12 +9,15 @@ var HttpError = class extends Error {
   status;
   statusText;
   body;
-  constructor(status2, statusText, body) {
+  /** Optional next-step guidance, overriding the status default (e.g. AppKey re-issue). */
+  hint;
+  constructor(status2, statusText, body, hint) {
     super(`HTTP ${status2} ${statusText}`);
     this.name = "HttpError";
     this.status = status2;
     this.statusText = statusText;
     this.body = body;
+    this.hint = hint;
   }
 };
 var InputError = class extends Error {
@@ -23,37 +26,38 @@ var InputError = class extends Error {
     this.name = "InputError";
   }
 };
-function toExitCode(err) {
-  if (err instanceof InputError) return 2;
-  if (err instanceof HttpError) {
-    if (err.status === 401 || err.status === 403) return 3;
+function toExitCode(err2) {
+  if (err2 instanceof InputError) return 2;
+  if (err2 instanceof HttpError) {
+    if (err2.status === 401 || err2.status === 403) return 3;
     return 1;
   }
   return 1;
 }
-function formatError(err) {
-  if (err instanceof HttpError) {
-    const serverMsg = serverError(err.body);
-    if (err.status === 401) {
-      return `Not authorized (HTTP 401)${serverMsg ? `: ${serverMsg}` : ""}. Run \`openbkn auth login\` and retry.`;
+function formatError(err2) {
+  if (err2 instanceof HttpError) {
+    const serverMsg = serverError(err2.body);
+    if (err2.status === 401) {
+      const next = err2.hint ?? "Run `openbkn auth login` and retry.";
+      return `Not authorized (HTTP 401)${serverMsg ? `: ${serverMsg}` : ""}. ${next}`;
     }
-    if (err.status === 403) {
+    if (err2.status === 403) {
       return `Forbidden (HTTP 403)${serverMsg ? `: ${serverMsg}` : " \u2014 admin privileges required"}.`;
     }
-    const detail = err.body ? `: ${truncate(err.body, 500)}` : "";
-    return `Request failed (HTTP ${err.status} ${err.statusText})${detail}`;
+    const detail = err2.body ? `: ${truncate(err2.body, 500)}` : "";
+    return `Request failed (HTTP ${err2.status} ${err2.statusText})${detail}`;
   }
-  if (err instanceof Error) {
-    const cause = err.cause;
+  if (err2 instanceof Error) {
+    const cause = err2.cause;
     if (cause?.code && isTlsCertError(cause.code)) {
       return `TLS certificate rejected (${cause.code}). The platform is likely self-signed \u2014 retry with \`-k\`/\`--insecure\`.`;
     }
-    if (err.message === "fetch failed" && cause?.message) {
+    if (err2.message === "fetch failed" && cause?.message) {
       return `Request failed: ${cause.message}${cause.code ? ` (${cause.code})` : ""}`;
     }
-    return err.message;
+    return err2.message;
   }
-  return String(err);
+  return String(err2);
 }
 function serverError(body) {
   if (!body) return "";
@@ -74,6 +78,36 @@ function truncate(s, n) {
 
 // src/auth/oauth.ts
 import { spawn } from "child_process";
+
+// src/api/tls.ts
+import { Agent, FormData as UndiciFormData, fetch as undiciFetch } from "undici";
+var insecureAgent;
+function insecureDispatcher() {
+  insecureAgent ??= new Agent({ connect: { rejectUnauthorized: false } });
+  return insecureAgent;
+}
+function isFormData(body) {
+  return typeof body === "object" && body !== null && body[Symbol.toStringTag] === "FormData";
+}
+function toUndiciBody(body) {
+  if (body instanceof UndiciFormData || !isFormData(body)) return body;
+  const form2 = new UndiciFormData();
+  for (const [name, value] of body.entries()) {
+    if (typeof value === "string") form2.append(name, value);
+    else form2.append(name, value, value.name);
+  }
+  return form2;
+}
+function tlsFetch(insecure, url, init) {
+  if (!insecure) return fetch(url, init);
+  return undiciFetch(url, {
+    ...init,
+    ...init?.body === void 0 || init?.body === null ? {} : { body: toUndiciBody(init.body) },
+    dispatcher: insecureDispatcher()
+  });
+}
+
+// src/auth/oauth.ts
 function normalizeBaseUrl(value) {
   return value.replace(/\/+$/, "");
 }
@@ -114,22 +148,9 @@ function mergeCookies(existing, res) {
   for (const sc of setCookies) add(sc.split(";")[0]?.trim() ?? "");
   return [...map.entries()].map(([k, v]) => `${k}=${v}`).join("; ");
 }
-async function fetchAuthStatus(baseUrl) {
-  try {
-    const res = await fetch(`${normalizeBaseUrl(baseUrl)}/install-status.json`, {
-      headers: { Accept: "application/json" }
-    });
-    if (!res.ok) return null;
-    const j = await res.json();
-    if (!j.auth) return null;
-    return { enabled: Boolean(j.auth.enabled), stack: j.auth.stack };
-  } catch {
-    return null;
-  }
-}
-async function refreshAccessToken(baseUrl, refreshToken, clientId = "openbkn-sdk") {
+async function refreshAccessToken(baseUrl, refreshToken, clientId = "openbkn-sdk", insecure) {
   const base = normalizeBaseUrl(baseUrl);
-  const res = await fetch(`${base}/oauth2/token`, {
+  const res = await tlsFetch(insecure, `${base}/oauth2/token`, {
     method: "POST",
     headers: {
       "Content-Type": "application/x-www-form-urlencoded",
@@ -159,10 +180,10 @@ var form = (body) => ({
   },
   body: new URLSearchParams(body).toString()
 });
-async function requestDeviceCode(base, clientId, scope, audience) {
+async function requestDeviceCode(base, clientId, scope, audience, insecure) {
   const params = { client_id: clientId, scope };
   if (audience) params.audience = audience;
-  const res = await fetch(`${base}/oauth2/device/auth`, form(params));
+  const res = await tlsFetch(insecure, `${base}/oauth2/device/auth`, form(params));
   if (!res.ok) {
     throw new Error(`Device auth failed (${res.status}): ${await res.text() || res.statusText}`);
   }
@@ -174,12 +195,13 @@ async function requestDeviceCode(base, clientId, scope, audience) {
   }
   return da;
 }
-async function pollDeviceToken(base, deviceCode, clientId, intervalMs, windowMs) {
+async function pollDeviceToken(base, deviceCode, clientId, intervalMs, windowMs, insecure) {
   let interval = intervalMs;
   const deadline = Date.now() + windowMs;
   while (Date.now() < deadline) {
     await new Promise((r) => setTimeout(r, interval));
-    const tokRes = await fetch(
+    const tokRes = await tlsFetch(
+      insecure,
       `${base}/oauth2/token`,
       form({ grant_type: DEVICE_GRANT, device_code: deviceCode, client_id: clientId })
     );
@@ -205,14 +227,27 @@ async function pollDeviceToken(base, deviceCode, clientId, intervalMs, windowMs)
 async function deviceLogin(baseUrl, opts = {}) {
   const base = normalizeBaseUrl(baseUrl);
   const clientId = opts.clientId ?? DEFAULT_DEVICE_CLIENT_ID;
-  const da = await requestDeviceCode(base, clientId, opts.scope ?? DEVICE_SCOPE, opts.audience);
+  const da = await requestDeviceCode(
+    base,
+    clientId,
+    opts.scope ?? DEVICE_SCOPE,
+    opts.audience,
+    opts.insecure
+  );
   opts.onPrompt?.({
     userCode: da.user_code,
     verificationUri: onBaseHost(base, da.verification_uri),
     verificationUriComplete: da.verification_uri_complete ? onBaseHost(base, da.verification_uri_complete) : void 0
   });
   const windowMs = Math.min(opts.timeoutMs ?? Number.POSITIVE_INFINITY, da.expires_in * 1e3);
-  return pollDeviceToken(base, da.device_code, clientId, (da.interval ?? 5) * 1e3, windowMs);
+  return pollDeviceToken(
+    base,
+    da.device_code,
+    clientId,
+    (da.interval ?? 5) * 1e3,
+    windowMs,
+    opts.insecure
+  );
 }
 function onBaseHost(base, uri) {
   try {
@@ -226,10 +261,16 @@ function onBaseHost(base, uri) {
 async function credentialDeviceLogin(baseUrl, username, password, opts = {}) {
   const base = normalizeBaseUrl(baseUrl);
   const clientId = opts.clientId ?? DEFAULT_DEVICE_CLIENT_ID;
-  const da = await requestDeviceCode(base, clientId, opts.scope ?? DEVICE_SCOPE, opts.audience);
+  const da = await requestDeviceCode(
+    base,
+    clientId,
+    opts.scope ?? DEVICE_SCOPE,
+    opts.audience,
+    opts.insecure
+  );
   let jar = "";
   const hop = async (url, init) => {
-    const r = await fetch(url, {
+    const r = await tlsFetch(opts.insecure, url, {
       method: init?.method ?? "GET",
       headers: { Cookie: jar, Accept: "text/html,*/*;q=0.8", ...init?.headers ?? {} },
       body: init?.body,
@@ -267,44 +308,132 @@ async function credentialDeviceLogin(baseUrl, username, password, opts = {}) {
     loc = r.headers.get("location");
   }
   const windowMs = Math.min(opts.timeoutMs ?? Number.POSITIVE_INFINITY, da.expires_in * 1e3);
-  return pollDeviceToken(base, da.device_code, clientId, (da.interval ?? 5) * 1e3, windowMs);
+  return pollDeviceToken(
+    base,
+    da.device_code,
+    clientId,
+    (da.interval ?? 5) * 1e3,
+    windowMs,
+    opts.insecure
+  );
+}
+
+// src/trace-context.ts
+import { randomBytes, randomUUID } from "crypto";
+var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+var REQUEST_ID_RE = /^req_[0-9A-Za-z_.-]+$/;
+var CORRELATION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+var RFC3339_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+var ALLOWED_BAGGAGE = /* @__PURE__ */ new Set(["bkn.account.type", "bkn.runtime.env"]);
+function isValidRequestId(value) {
+  return typeof value === "string" && REQUEST_ID_RE.test(value);
+}
+function isValidCorrelationId(value) {
+  return typeof value === "string" && CORRELATION_ID_RE.test(value.trim());
+}
+function isValidTraceparent(value) {
+  if (typeof value !== "string") return false;
+  const match = TRACEPARENT_RE.exec(value);
+  if (!match) return false;
+  const [, traceId, spanId] = match;
+  return traceId !== "0".repeat(32) && spanId !== "0".repeat(16);
+}
+function createTraceContext(opts = {}) {
+  const requestId = isValidRequestId(opts.requestId) ? opts.requestId : `req_${randomUUID()}`;
+  const traceparent = isValidTraceparent(opts.traceparent) ? opts.traceparent : newTraceparent();
+  const baggage = filterBaggage(opts.baggage);
+  const conversationId = isValidCorrelationId(opts.conversationId) ? opts.conversationId.trim() : void 0;
+  const interactionId = isValidCorrelationId(opts.interactionId) ? opts.interactionId.trim() : void 0;
+  const operationId = isValidCorrelationId(opts.operationId) ? opts.operationId.trim() : void 0;
+  const attempt = Number.isInteger(opts.attempt) && (opts.attempt ?? 0) >= 1 && (opts.attempt ?? 0) <= 1e3 ? opts.attempt : void 0;
+  const observedAt = isValidObservedAt(opts.observedAt) ? opts.observedAt : void 0;
+  return {
+    requestId,
+    traceparent,
+    ...conversationId ? { conversationId } : {},
+    ...interactionId ? { interactionId } : {},
+    ...operationId ? { operationId } : {},
+    ...attempt ? { attempt } : {},
+    ...observedAt ? { observedAt } : {},
+    ...Object.keys(baggage).length > 0 ? { baggage } : {}
+  };
+}
+function createOperationTraceContext(trace2) {
+  return {
+    ...trace2,
+    operationId: trace2.operationId ?? `op_${randomUUID()}`,
+    attempt: trace2.attempt ?? 1,
+    observedAt: isValidObservedAt(trace2.observedAt) ? trace2.observedAt : (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function isValidObservedAt(value) {
+  return typeof value === "string" && RFC3339_RE.test(value) && !Number.isNaN(Date.parse(value));
+}
+function filterBaggage(baggage) {
+  const filtered = {};
+  for (const [key, value] of Object.entries(baggage ?? {})) {
+    if (ALLOWED_BAGGAGE.has(key) && value !== "") filtered[key] = value;
+  }
+  return filtered;
+}
+function serializeBaggage(baggage) {
+  const filtered = filterBaggage(baggage);
+  const entries = Object.entries(filtered);
+  if (entries.length === 0) return void 0;
+  return entries.map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join(",");
+}
+function newTraceparent() {
+  return `00-${randomHex(16)}-${randomHex(8)}-01`;
+}
+function randomHex(bytes) {
+  let value = randomBytes(bytes).toString("hex");
+  while (/^0+$/.test(value)) value = randomBytes(bytes).toString("hex");
+  return value;
 }
 
 // src/api/headers.ts
 function buildHeaders(ctx, extra) {
+  const baggage = serializeBaggage(ctx.trace?.baggage);
   return {
-    // No token = a no-auth platform (no bkn-safe); send no Authorization.
-    ...ctx.token ? { authorization: `Bearer ${ctx.token}`, token: ctx.token } : {},
+    authorization: `Bearer ${ctx.token}`,
     "x-business-domain": ctx.businessDomain,
+    ...ctx.trace ? {
+      "bkn-request-id": ctx.trace.requestId,
+      "x-request-id": ctx.trace.requestId,
+      traceparent: ctx.trace.traceparent,
+      ...ctx.trace.conversationId ? { "bkn-conversation-id": ctx.trace.conversationId } : {},
+      ...ctx.trace.interactionId ? { "bkn-interaction-id": ctx.trace.interactionId } : {},
+      ...ctx.trace.operationId ? { "bkn-operation-id": ctx.trace.operationId } : {},
+      ...ctx.trace.attempt ? { "bkn-attempt": String(ctx.trace.attempt) } : {},
+      ...ctx.trace.observedAt ? { "bkn-event-observed-at": ctx.trace.observedAt } : {}
+    } : {},
+    ...baggage ? { baggage } : {},
     ...extra
   };
 }
 
-// src/api/tls.ts
-function applyTls(ctx) {
-  if (ctx.insecure && process.env.NODE_TLS_REJECT_UNAUTHORIZED !== "0") {
-    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-  }
-}
-
 // src/api/http.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 async function request(ctx, path, init = {}) {
   const url = new URL(path.startsWith("http") ? path : `${ctx.baseUrl}${path}`);
   for (const [k, v] of Object.entries(init.query ?? {})) {
-    if (v !== void 0) url.searchParams.set(k, String(v));
+    if (Array.isArray(v)) {
+      for (const item of v) url.searchParams.append(k, String(item));
+    } else if (v !== void 0) {
+      url.searchParams.set(k, String(v));
+    }
   }
-  applyTls(ctx);
   const hasBody = init.body !== void 0;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), init.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-  const send = () => fetch(url, {
+  const send = () => tlsFetch(ctx.insecure, url, {
     method: init.method ?? (hasBody ? "POST" : "GET"),
     headers: buildHeaders(ctx, {
       ...hasBody ? { "content-type": "application/json" } : {},
       ...init.headers
     }),
     body: hasBody ? JSON.stringify(init.body) : void 0,
+    redirect: init.redirect,
     signal: controller.signal
   });
   try {
@@ -313,16 +442,27 @@ async function request(ctx, path, init = {}) {
       res = await send();
     }
     const text = await res.text();
-    if (!res.ok) throw new HttpError(res.status, res.statusText, text);
+    if (!res.ok) throw new HttpError(res.status, res.statusText, text, hintFor(ctx, res.status));
     return text ? JSON.parse(text) : void 0;
   } finally {
     clearTimeout(timer);
   }
 }
+function hintFor(ctx, status2) {
+  if (status2 === 401 && ctx.token.startsWith("bak_")) {
+    return "AppKey invalid / expired / revoked / owner disabled \u2014 re-issue with `openbkn appkey create` (or `appkey regenerate <id>`). Do not auto-retry.";
+  }
+  return void 0;
+}
 async function tryRefresh(ctx) {
   if (!ctx.refresh) return false;
   try {
-    const t = await refreshAccessToken(ctx.baseUrl, ctx.refresh.refreshToken, ctx.refresh.clientId);
+    const t = await refreshAccessToken(
+      ctx.baseUrl,
+      ctx.refresh.refreshToken,
+      ctx.refresh.clientId,
+      ctx.insecure
+    );
     ctx.token = t.accessToken;
     if (t.refreshToken) ctx.refresh.refreshToken = t.refreshToken;
     ctx.refresh.persist(t);
@@ -367,6 +507,7 @@ function isExpired(claims, nowMs = Date.now()) {
 
 // src/config/store.ts
 var PROFILE_RE = /^[A-Za-z0-9_-]{1,64}$/;
+var USER_ID_RE = /^[A-Za-z0-9._@-]{1,128}$/;
 var IS_WIN = process.platform === "win32";
 function configDir() {
   return process.env.BKN_CONFIG_DIR ?? join(homedir(), ".bkn");
@@ -393,7 +534,14 @@ function userDir(baseUrl, userId) {
   return join(platformDir(baseUrl), "users", userId);
 }
 function userIdFromToken(token) {
-  return decodeJwt(token.idToken ?? "")?.sub ?? decodeJwt(token.accessToken)?.sub ?? "default";
+  const sub = decodeJwt(token.idToken ?? "")?.sub ?? decodeJwt(token.accessToken)?.sub;
+  if (sub === void 0) return "default";
+  if (typeof sub !== "string" || !USER_ID_RE.test(sub) || sub === "." || sub === "..") {
+    throw new Error(
+      `Token subject '${String(sub)}' is not a usable user id (expected 1-128 chars from [A-Za-z0-9._@-]). Refusing to store this token.`
+    );
+  }
+  return sub;
 }
 function readState() {
   return readJson(statePath()) ?? {};
@@ -418,10 +566,10 @@ function readToken(baseUrl, userId = activeUserId(baseUrl)) {
   if (!userId) return void 0;
   return readJson(join(userDir(baseUrl, userId), "token.json")) ?? void 0;
 }
-function writeToken(baseUrl, token) {
+function writeToken(baseUrl, token, opts = {}) {
   const userId = userIdFromToken(token);
   writeJson(join(userDir(baseUrl, userId), "token.json"), token, 384);
-  setActiveUser(baseUrl, userId);
+  if (opts.setActive !== false) setActiveUser(baseUrl, userId);
   return userId;
 }
 function deleteToken(baseUrl, userId = activeUserId(baseUrl)) {
@@ -460,6 +608,14 @@ function listPlatforms() {
   }
   return out;
 }
+function findUserId(baseUrl, userOrName) {
+  const users = listPlatforms().find((p) => p.baseUrl === baseUrl)?.users ?? [];
+  const match = users.find((u) => u.userId === userOrName) ?? users.find((u) => (u.username ?? u.displayName) === userOrName);
+  return match?.userId ?? null;
+}
+function usersOfPlatform(baseUrl) {
+  return listPlatforms().find((p) => p.baseUrl === baseUrl)?.users ?? [];
+}
 function decodeKey(key) {
   try {
     const b64 = key.replace(/-/g, "+").replace(/_/g, "/");
@@ -485,6 +641,14 @@ function writeJson(path, value, mode = 384) {
 }
 
 // src/config/resolve.ts
+function resolveUserId(baseUrl, userOrName) {
+  const id = findUserId(baseUrl, userOrName);
+  if (id) return id;
+  const known = usersOfPlatform(baseUrl).map((u) => u.username ?? u.userId).join(", ");
+  throw new InputError(
+    `No saved user '${userOrName}' on ${baseUrl}. Saved: ${known || "(none)"}. See \`openbkn auth users ${baseUrl}\`.`
+  );
+}
 function resolveContext(opts = {}) {
   const baseUrl = opts.baseUrl ?? process.env.BKN_BASE_URL ?? activePlatform();
   if (!baseUrl) {
@@ -493,22 +657,29 @@ function resolveContext(opts = {}) {
     );
   }
   const normalized = baseUrl.replace(/\/+$/, "");
-  const stored = readToken(normalized);
+  const user = opts.user ?? process.env.BKN_USER;
+  const stored = user ? readToken(normalized, resolveUserId(normalized, user)) : readToken(normalized);
   const explicit = opts.token ?? process.env.BKN_TOKEN;
   const token = explicit ?? stored?.accessToken ?? "";
-  if (!token && !stored?.noAuth) {
+  if (!token) {
     throw new InputError("No access token. Set BKN_TOKEN or run `openbkn auth login`.");
   }
   const insecure = opts.insecure ?? stored?.tlsInsecure ?? false;
   const refresh = !explicit && stored?.refreshToken ? {
     refreshToken: stored.refreshToken,
     persist: (t) => {
-      writeToken(normalized, {
-        ...stored,
-        accessToken: t.accessToken,
-        refreshToken: t.refreshToken ?? stored.refreshToken,
-        idToken: t.idToken ?? stored.idToken
-      });
+      writeToken(
+        normalized,
+        {
+          ...stored,
+          accessToken: t.accessToken,
+          refreshToken: t.refreshToken ?? stored.refreshToken,
+          idToken: t.idToken ?? stored.idToken
+        },
+        // `--user` picks an identity for this command only; a refresh
+        // must not promote it to the default for the next one.
+        { setActive: !user }
+      );
     }
   } : void 0;
   return {
@@ -516,6 +687,13 @@ function resolveContext(opts = {}) {
     token,
     businessDomain: opts.businessDomain ?? readPlatformConfig(normalized).businessDomain ?? DEFAULT_BUSINESS_DOMAIN,
     insecure,
+    ...opts.evidenceIngestToken ?? process.env.BKN_TRACE_EVIDENCE_INGEST_TOKEN ? {
+      evidenceIngestToken: opts.evidenceIngestToken ?? process.env.BKN_TRACE_EVIDENCE_INGEST_TOKEN
+    } : {},
+    // Correlation ids come from `opts.trace` only. The CLI reads its flags and
+    // env vars in `commands/_shared.ts`; a library client must not inherit an
+    // ambient interaction id it would then freeze for its whole lifetime.
+    trace: createTraceContext(opts.trace),
     ...refresh ? { refresh } : {}
   };
 }
@@ -571,6 +749,13 @@ async function setUserPasswordSafe(ctx, userId, password) {
   });
   return { ok: true };
 }
+async function changePasswordSafe(ctx, account, oldPassword, newPassword) {
+  await request(ctx, "/api/safe/v1/auth/change-password", {
+    method: "POST",
+    body: { account, old_password: oldPassword, new_password: newPassword }
+  });
+  return { ok: true };
+}
 function getUserRolesSafe(ctx, userId) {
   return request(ctx, `${ADMIN}/role-bindings`, { query: { accessor_id: userId } });
 }
@@ -684,6 +869,43 @@ async function setRolePermissionSafe(ctx, roleId, grant, perm) {
   });
   return { ok: true };
 }
+function getLicenseSafe(ctx) {
+  return request(ctx, `${ADMIN}/license`);
+}
+async function importLicenseSafe(ctx, licenseText, opts = {}) {
+  const text = licenseText.trim();
+  if (!text) throw new InputError("license text is empty");
+  try {
+    return await request(ctx, `${ADMIN}/license/${opts.receipt ? "receipt" : "import"}`, {
+      method: "POST",
+      body: { license: text }
+    });
+  } catch (err2) {
+    if (err2 instanceof HttpError) {
+      const stored = storedImport(err2.body);
+      if (stored) return stored;
+    }
+    throw err2;
+  }
+}
+function storedImport(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && parsed.stored === true) return parsed;
+  } catch {
+  }
+  return null;
+}
+function activateLicenseSafe(ctx) {
+  return request(ctx, `${ADMIN}/license/activate`, { method: "POST" });
+}
+async function removeLicenseSafe(ctx) {
+  await request(ctx, `${ADMIN}/license`, { method: "DELETE" });
+  return { ok: true };
+}
+function getLicenseFingerprintSafe(ctx) {
+  return request(ctx, `${ADMIN}/license/fingerprint`);
+}
 
 // src/resources/admin.ts
 var DEFAULT_NEW_USER_PASSWORD = "openbkn";
@@ -744,7 +966,13 @@ function admin(ctx) {
     roleUpdate: (roleId, input) => updateRoleSafe(ctx, roleId, input),
     roleDelete: (roleId) => deleteRoleSafe(ctx, roleId),
     rolePermission: (roleId, grant, resourceType, resourceId, operations) => setRolePermissionSafe(ctx, roleId, grant, { resourceType, resourceId, operations }),
-    auditList: (_opts) => notOnSafe("audit list")
+    auditList: (_opts) => notOnSafe("audit list"),
+    // ── license (cluster license hub; weak judgements — display/ops only) ──
+    licenseGet: () => getLicenseSafe(ctx),
+    licenseImport: (licenseText, opts) => importLicenseSafe(ctx, licenseText, opts),
+    licenseActivate: () => activateLicenseSafe(ctx),
+    licenseRemove: () => removeLicenseSafe(ctx),
+    licenseFingerprint: () => getLicenseFingerprintSafe(ctx)
   };
 }
 
@@ -816,7 +1044,6 @@ function extractText(result) {
   return "";
 }
 async function sendChat(ctx, info, query, opts = {}) {
-  applyTls(ctx);
   const body = {
     agent_id: info.id,
     agent_key: info.key,
@@ -827,7 +1054,7 @@ async function sendChat(ctx, info, query, opts = {}) {
   if (opts.conversationId) body.conversation_id = opts.conversationId;
   const res = await authFetch(
     ctx,
-    () => fetch(`${ctx.baseUrl}${FACTORY}/v1/app/${info.key}/chat/completion`, {
+    () => tlsFetch(ctx.insecure, `${ctx.baseUrl}${FACTORY}/v1/app/${info.key}/chat/completion`, {
       method: "POST",
       headers: {
         ...buildHeaders(ctx),
@@ -1029,16 +1256,20 @@ function nextId() {
 function mcpUrl(ctx) {
   return `${ctx.baseUrl}${MCP_PATH}`;
 }
+function operationContext(ctx) {
+  return ctx.trace ? { ...ctx, trace: createOperationTraceContext(ctx.trace) } : ctx;
+}
+function mcpInfo(ctx) {
+  return request(ctx, `${MCP_PATH}/info`);
+}
 function headers(ctx, knId, sessionId) {
-  const h = {
+  return buildHeaders(ctx, {
     "content-type": "application/json",
     accept: "application/json, text/event-stream",
     "x-kn-id": knId,
     "mcp-protocol-version": PROTOCOL,
-    authorization: `Bearer ${ctx.token}`
-  };
-  if (sessionId) h["mcp-session-id"] = sessionId;
-  return h;
+    ...sessionId ? { "mcp-session-id": sessionId } : {}
+  });
 }
 function parseBody(text) {
   try {
@@ -1050,10 +1281,9 @@ function parseBody(text) {
   }
 }
 async function post(ctx, knId, sessionId, body) {
-  applyTls(ctx);
   const res = await authFetch(
     ctx,
-    () => fetch(mcpUrl(ctx), {
+    () => tlsFetch(ctx.insecure, mcpUrl(ctx), {
       method: "POST",
       headers: headers(ctx, knId, sessionId),
       body: JSON.stringify(body)
@@ -1100,8 +1330,9 @@ function unwrap(parsed) {
   return result;
 }
 async function callTool(ctx, knId, name, args) {
-  const sessionId = await ensureSession(ctx, knId);
-  const { text } = await post(ctx, knId, sessionId, {
+  const operationCtx = operationContext(ctx);
+  const sessionId = await ensureSession(operationCtx, knId);
+  const { text } = await post(operationCtx, knId, sessionId, {
     jsonrpc: "2.0",
     method: "tools/call",
     params: { name, arguments: args },
@@ -1110,8 +1341,9 @@ async function callTool(ctx, knId, name, args) {
   return unwrap(parseBody(text));
 }
 async function callMethod(ctx, knId, method, params = {}) {
-  const sessionId = await ensureSession(ctx, knId);
-  const { text } = await post(ctx, knId, sessionId, {
+  const operationCtx = operationContext(ctx);
+  const sessionId = await ensureSession(operationCtx, knId);
+  const { text } = await post(operationCtx, knId, sessionId, {
     jsonrpc: "2.0",
     method,
     params: Object.keys(params).length > 0 ? params : void 0,
@@ -1135,6 +1367,17 @@ function findSkills(ctx, knId, objectTypeId, topK) {
   if (topK !== void 0) args.top_k = topK;
   return callTool(ctx, knId, "find_skills", args);
 }
+function getKnDetail(ctx, knId, detailLevel) {
+  const args = { response_format: "json" };
+  if (detailLevel) args.detail_level = detailLevel;
+  return callTool(ctx, knId, "get_kn_detail", args);
+}
+function getObjectTypes(ctx, knId, ids) {
+  return callTool(ctx, knId, "get_object_types", { ids, response_format: "json" });
+}
+function getRelationTypes(ctx, knId, ids) {
+  return callTool(ctx, knId, "get_relation_types", { ids, response_format: "json" });
+}
 function listTools(ctx, knId) {
   return callMethod(ctx, knId, "tools/list");
 }
@@ -1169,8 +1412,16 @@ function context(ctx) {
     searchSchema: (knId, query, opts) => searchSchema(ctx, knId, query, opts),
     queryObjectInstance: (knId, args) => queryObjectInstance(ctx, knId, args),
     findSkills: (knId, objectTypeId, topK) => findSkills(ctx, knId, objectTypeId, topK),
+    // Progressive schema disclosure: skeleton first (summary), then drill down.
+    knDetail: (knId, detailLevel) => getKnDetail(ctx, knId, detailLevel),
+    objectTypes: (knId, ids) => getObjectTypes(ctx, knId, ids),
+    relationTypes: (knId, ids) => getRelationTypes(ctx, knId, ids),
+    info: () => mcpInfo(ctx),
     tools: (knId) => listTools(ctx, knId),
     toolCall: (knId, name, args) => callTool(ctx, knId, name, args),
+    // Generic MCP method passthrough — covers methods not yet wrapped, so the
+    // surface doesn't have to grow every time the server adds one.
+    callMethod: (knId, method, params) => callMethod(ctx, knId, method, params),
     queryInstanceSubgraph: (knId, args) => queryInstanceSubgraph(ctx, knId, args),
     logicProperties: (knId, args) => getLogicProperties(ctx, knId, args),
     actionInfo: (knId, args) => getActionInfo(ctx, knId, args),
@@ -1227,7 +1478,11 @@ async function executeDataflow(ctx, body, opts = {}) {
 }
 function listDataflowRuns(ctx, dagId, opts = {}) {
   return request(ctx, `${BASE2}/dag/${encodeURIComponent(dagId)}/results`, {
-    query: { since: opts.since || void 0 }
+    query: {
+      since: opts.since || void 0,
+      page: opts.page,
+      limit: opts.limit && opts.limit > 0 ? opts.limit : void 0
+    }
   });
 }
 function runDataflowRemote(ctx, dagId, url, name) {
@@ -1283,9 +1538,11 @@ function deleteKnowledgeNetwork(ctx, knId) {
 function updateKnowledgeNetwork(ctx, knId, body) {
   return request(ctx, `${ONTOLOGY_BASE}/${encodeURIComponent(knId)}`, { method: "PUT", body });
 }
+var QUERY_OVER_POST = { "X-HTTP-Method-Override": "GET" };
 function querySubgraph(ctx, knId, body) {
   return request(ctx, `${ONTOLOGY_QUERY_BASE}/${encodeURIComponent(knId)}/subgraph`, {
     method: "POST",
+    headers: QUERY_OVER_POST,
     body
   });
 }
@@ -1317,13 +1574,7 @@ function queryObjectTypeInstances(ctx, knId, otId, body) {
   return request(
     ctx,
     `${ONTOLOGY_QUERY_BASE}/${encodeURIComponent(knId)}/object-types/${encodeURIComponent(otId)}`,
-    { method: "POST", body }
-  );
-}
-function getObjectTypeProperties(ctx, knId, otId) {
-  return request(
-    ctx,
-    `${ONTOLOGY_QUERY_BASE}/${encodeURIComponent(knId)}/object-types/${encodeURIComponent(otId)}/properties`
+    { method: "POST", headers: QUERY_OVER_POST, body }
   );
 }
 function queryActionType(ctx, knId, atId, body) {
@@ -1490,7 +1741,19 @@ function listResources2(ctx, opts = {}) {
       catalog_id: opts.datasourceId || void 0,
       name: opts.name || void 0,
       category: opts.category || void 0,
-      limit: opts.limit && opts.limit > 0 ? opts.limit : void 0
+      status: opts.status || void 0,
+      database: opts.database || void 0,
+      // Same `/resources` endpoint as `catalogResources`: limit=-1 (NO_LIMIT)
+      // fetches every row; any other non-positive/invalid value falls back to
+      // the backend default.
+      limit: Number.isFinite(opts.limit) && (opts.limit > 0 || opts.limit === -1) ? opts.limit : void 0,
+      offset: opts.offset,
+      sort: opts.sort,
+      direction: opts.direction,
+      include_extensions: opts.includeExtensions === void 0 ? void 0 : String(opts.includeExtensions),
+      include_extension_keys: opts.includeExtensionKeys || void 0,
+      extension_key: opts.extensionPairs?.map((p) => p.key),
+      extension_value: opts.extensionPairs?.map((p) => p.value)
     }
   });
 }
@@ -1500,32 +1763,130 @@ function getResource(ctx, id) {
 function createResourceRaw(ctx, body) {
   return request(ctx, BASE3, { method: "POST", body });
 }
-function createResource(ctx, opts) {
+function updateResourceRaw(ctx, id, body) {
+  return request(ctx, `${BASE3}/${encodeURIComponent(id)}`, { method: "PUT", body });
+}
+async function updateResource(ctx, id, patch) {
+  const current = firstResource(await getResource(ctx, id));
+  return updateResourceRaw(ctx, id, resourceUpdateBody(id, current, patch));
+}
+async function configureResourceIndex(ctx, id, opts) {
+  const current = firstResource(await getResource(ctx, id));
+  const schema = (current.schema_definition ?? []).map((prop) => ({ ...prop }));
+  const indexConfig = {
+    ...current.index_config ?? {},
+    ...opts.buildKeyFields?.length ? { build_key_fields: opts.buildKeyFields } : {},
+    ...opts.embeddingModel ? { default_embedding_model: opts.embeddingModel } : {},
+    ...opts.fulltextAnalyzer ? { default_fulltext_analyzer: opts.fulltextAnalyzer } : {}
+  };
+  for (const field of opts.embeddingFields ?? []) {
+    ensureFeature(
+      schema,
+      field,
+      "vector",
+      opts.embeddingModel ? { embedding_model: opts.embeddingModel } : void 0
+    );
+  }
+  for (const field of opts.fulltextFields ?? []) {
+    ensureFeature(
+      schema,
+      field,
+      "fulltext",
+      opts.fulltextAnalyzer ? { analyzer: opts.fulltextAnalyzer } : void 0
+    );
+  }
+  return updateResourceRaw(
+    ctx,
+    id,
+    resourceUpdateBody(id, current, { schemaDefinition: schema, indexConfig })
+  );
+}
+function resourceUpdateBody(id, current, patch) {
   const body = {
-    name: opts.name,
-    catalog_id: opts.catalogId,
-    category: "table",
-    source_identifier: opts.sourceIdentifier
+    id,
+    name: patch.name ?? current.name,
+    catalog_id: patch.catalogId ?? current.catalog_id,
+    tags: patch.tags ?? current.tags ?? [],
+    description: patch.description ?? current.description ?? "",
+    category: patch.category ?? current.category,
+    status: patch.status ?? current.status,
+    database: patch.database ?? current.database,
+    source_identifier: patch.sourceIdentifier ?? current.source_identifier,
+    source_metadata: patch.sourceMetadata ?? current.source_metadata,
+    schema_definition: patch.schemaDefinition ?? current.schema_definition,
+    index_config: patch.indexConfig === void 0 ? current.index_config : patch.indexConfig,
+    logic_definition: patch.logicDefinition ?? current.logic_definition
   };
-  if (opts.fields && opts.fields.length > 0) body.schema_definition = opts.fields;
-  return request(ctx, BASE3, { method: "POST", body });
+  if (patch.extensions !== void 0 || current.extensions !== void 0) {
+    body.extensions = patch.extensions ?? current.extensions;
+  }
+  return body;
+}
+function ensureFeature(schema, field, featureType, config) {
+  const prop = schema.find((p) => p.name === field);
+  if (!prop) throw new Error(`resource field '${field}' not found in schema_definition`);
+  const features = [...prop.features ?? []];
+  const existing = features.find(
+    (f) => f.feature_type === featureType && (f.ref_property || field) === field
+  );
+  if (existing) {
+    existing.ref_property = existing.ref_property || field;
+    existing.config = { ...existing.config ?? {}, ...config ?? {} };
+  } else {
+    features.push({
+      name: `${field}_${featureType}`,
+      feature_type: featureType,
+      ref_property: field,
+      is_default: false,
+      is_native: false,
+      ...config ? { config } : {}
+    });
+  }
+  prop.features = features;
 }
-function deleteResource(ctx, id) {
-  return request(ctx, `${BASE3}/${encodeURIComponent(id)}`, { method: "DELETE" });
+function firstResource(result) {
+  if (result && typeof result === "object") {
+    const o = result;
+    if (Array.isArray(o.entries)) return o.entries[0] ?? {};
+    return o;
+  }
+  return {};
+}
+function deleteResource(ctx, id, opts = {}) {
+  const ids = Array.isArray(id) ? id : [id];
+  return request(ctx, `${BASE3}/${ids.map(encodeURIComponent).join(",")}`, {
+    method: "DELETE",
+    query: {
+      ignore_missing: opts.ignoreMissing === void 0 ? void 0 : String(opts.ignoreMissing)
+    }
+  });
 }
 async function findResource(ctx, name, opts = {}) {
-  const result = await listResources2(ctx, { name, datasourceId: opts.datasourceId });
+  const result = await listResources2(ctx, {
+    name,
+    datasourceId: opts.datasourceId,
+    limit: opts.limit
+  });
   const list = Array.isArray(result) ? result : result.entries ?? [];
   return opts.exact ? list.filter((r) => r.name === name) : list;
 }
 function queryResource(ctx, id, opts = {}) {
-  return request(ctx, `${BASE3}/${encodeURIComponent(id)}/data`, {
-    method: "POST",
-    body: {
+  const body = opts.cursor ? {
+    paging: { cursor: opts.cursor },
+    need_total: opts.needTotal ?? false
+  } : {
+    paging: {
+      mode: opts.pagingMode ?? "single",
       limit: opts.limit ?? 50,
       offset: opts.offset ?? 0,
-      need_total: opts.needTotal ?? false
-    }
+      ...opts.keepAliveSec !== void 0 ? { keep_alive_sec: opts.keepAliveSec } : {}
+    },
+    need_total: opts.needTotal ?? false
+  };
+  return request(ctx, `${BASE3}/${encodeURIComponent(id)}/data`, {
+    method: "POST",
+    headers: { "X-HTTP-Method-Override": "GET" },
+    body
   });
 }
 
@@ -2733,7 +3094,6 @@ function knPath(knId, path) {
   return `${BASE4}/${encodeURIComponent(knId)}/${path}`;
 }
 async function uploadBkn(ctx, tarBuffer, opts = {}) {
-  applyTls(ctx);
   const url = new URL(`${ctx.baseUrl}${BKNS}`);
   url.searchParams.set("branch", opts.branch ?? "main");
   const form2 = new FormData();
@@ -2744,17 +3104,19 @@ async function uploadBkn(ctx, tarBuffer, opts = {}) {
   );
   const res = await authFetch(
     ctx,
-    () => fetch(url, { method: "POST", headers: buildHeaders(ctx), body: form2 })
+    () => tlsFetch(ctx.insecure, url, { method: "POST", headers: buildHeaders(ctx), body: form2 })
   );
   const text = await res.text();
   if (!res.ok) throw new HttpError(res.status, res.statusText, text);
   return text ? JSON.parse(text) : void 0;
 }
 async function downloadBkn(ctx, knId, opts = {}) {
-  applyTls(ctx);
   const url = new URL(`${ctx.baseUrl}${BKNS}/${encodeURIComponent(knId)}`);
   url.searchParams.set("branch", opts.branch ?? "main");
-  const res = await authFetch(ctx, () => fetch(url, { method: "GET", headers: buildHeaders(ctx) }));
+  const res = await authFetch(
+    ctx,
+    () => tlsFetch(ctx.insecure, url, { method: "GET", headers: buildHeaders(ctx) })
+  );
   if (!res.ok) throw new HttpError(res.status, res.statusText, await res.text());
   return Buffer.from(await res.arrayBuffer());
 }
@@ -2762,7 +3124,11 @@ function listBknResources(ctx) {
   return request(ctx, "/api/bkn-backend/v1/resources");
 }
 function relationTypePaths(ctx, knId, body) {
-  return request(ctx, knPath(knId, "relation-type-paths"), { method: "POST", body });
+  return request(ctx, knPath(knId, "relation-type-paths"), {
+    method: "POST",
+    headers: { "X-HTTP-Method-Override": "GET" },
+    body
+  });
 }
 function listConceptGroups(ctx, knId) {
   return request(ctx, knPath(knId, "concept-groups"));
@@ -2823,18 +3189,6 @@ function setActionScheduleStatus(ctx, knId, scheduleId, body) {
 function deleteActionSchedules(ctx, knId, ids) {
   return request(ctx, knPath(knId, `action-schedules/${ids}`), { method: "DELETE" });
 }
-function listJobs(ctx, knId) {
-  return request(ctx, knPath(knId, "jobs"));
-}
-function getJob(ctx, knId, jobId) {
-  return request(ctx, knPath(knId, `jobs/${encodeURIComponent(jobId)}`));
-}
-function getJobTasks(ctx, knId, jobId) {
-  return request(ctx, knPath(knId, `jobs/${encodeURIComponent(jobId)}/tasks`));
-}
-function deleteJobs(ctx, knId, ids) {
-  return request(ctx, knPath(knId, `jobs/${ids}`), { method: "DELETE" });
-}
 
 // src/api/vega.ts
 import { z } from "zod";
@@ -2843,10 +3197,7 @@ var BuildMode = z.enum(["batch", "streaming"]);
 var CreateBuildTaskRequest = z.object({
   resource_id: z.string().min(1),
   mode: BuildMode,
-  embedding_fields: z.array(z.string()).optional(),
-  build_key_fields: z.array(z.string()).optional(),
-  embedding_model: z.string().optional(),
-  model_dimensions: z.number().int().positive().optional()
+  execute_type: z.enum(["incremental", "full"]).optional()
 });
 var BuildTask = z.object({
   id: z.string(),
@@ -2857,31 +3208,83 @@ var BuildTask = z.object({
   total_count: z.number().optional(),
   synced_count: z.number().optional(),
   vectorized_count: z.number().optional(),
-  embedding_fields: z.string().optional(),
-  build_key_fields: z.string().optional(),
-  embedding_model: z.string().optional(),
-  model_dimensions: z.number().optional()
+  index_config: z.unknown().optional(),
+  catalog_id: z.string().optional(),
+  index_health: z.object({
+    embedding: z.string(),
+    fulltext: z.string(),
+    usable: z.boolean()
+  }).passthrough().optional()
 }).passthrough();
 async function createBuildTask(ctx, req) {
   const p = CreateBuildTaskRequest.parse(req);
   const body = {
     resource_id: p.resource_id,
     mode: p.mode,
-    ...p.embedding_fields?.length ? { embedding_fields: p.embedding_fields.join(",") } : {},
-    ...p.build_key_fields?.length ? { build_key_fields: p.build_key_fields.join(",") } : {},
-    ...p.embedding_model ? { embedding_model: p.embedding_model } : {},
-    ...p.model_dimensions ? { model_dimensions: p.model_dimensions } : {}
+    ...p.execute_type ? { execute_type: p.execute_type } : {}
   };
   const res = await request(ctx, `${VEGA_BASE}/build-tasks`, { method: "POST", body });
   return BuildTask.parse(res);
 }
+function listBuildTasks(ctx, opts = {}) {
+  return request(ctx, `${VEGA_BASE}/build-tasks`, {
+    query: {
+      limit: opts.limit,
+      offset: opts.offset,
+      resource_id: opts.resourceId || void 0,
+      catalog_id: opts.catalogId || void 0,
+      status: Array.isArray(opts.status) ? opts.status.join(",") : opts.status || void 0,
+      active: opts.active === void 0 ? void 0 : String(opts.active),
+      mode: opts.mode,
+      order_by: opts.orderBy,
+      order: opts.order
+    }
+  });
+}
 async function getBuildTask(ctx, taskId) {
   const res = await request(ctx, `${VEGA_BASE}/build-tasks/${encodeURIComponent(taskId)}`);
   return BuildTask.parse(res);
 }
+function deleteBuildTasks(ctx, ids, opts = {}) {
+  return request(ctx, `${VEGA_BASE}/build-tasks/${ids.map(encodeURIComponent).join(",")}`, {
+    method: "DELETE",
+    query: {
+      ignore_missing: opts.ignoreMissing === void 0 ? void 0 : String(opts.ignoreMissing),
+      delete_active_index: opts.deleteActiveIndex === void 0 ? void 0 : String(opts.deleteActiveIndex)
+    }
+  });
+}
+function startBuildTask(ctx, taskId, opts = {}) {
+  return request(ctx, `${VEGA_BASE}/build-tasks/${encodeURIComponent(taskId)}/start`, {
+    method: "POST",
+    body: opts.reset === void 0 ? {} : { reset: opts.reset }
+  });
+}
+function stopBuildTask(ctx, taskId) {
+  return request(ctx, `${VEGA_BASE}/build-tasks/${encodeURIComponent(taskId)}/stop`, {
+    method: "POST"
+  });
+}
+function runSql(ctx, body) {
+  return request(ctx, `${VEGA_BASE}/resources/query`, { method: "POST", body });
+}
 async function listCatalogs(ctx, opts = {}) {
   return request(ctx, `${VEGA_BASE}/catalogs`, {
-    query: { limit: opts.limit, offset: opts.offset }
+    query: {
+      limit: opts.limit,
+      offset: opts.offset,
+      name: opts.name || void 0,
+      tag: opts.tag || void 0,
+      type: opts.type || void 0,
+      enabled: opts.enabled === void 0 ? void 0 : String(opts.enabled),
+      health_check_status: opts.healthCheckStatus || void 0,
+      include_extensions: opts.includeExtensions === void 0 ? void 0 : String(opts.includeExtensions),
+      include_extension_keys: opts.includeExtensionKeys || void 0,
+      extension_key: opts.extensionPairs?.map((p) => p.key),
+      extension_value: opts.extensionPairs?.map((p) => p.value),
+      sort: opts.sort,
+      direction: opts.direction
+    }
   });
 }
 function getCatalog(ctx, id) {
@@ -2891,18 +3294,49 @@ function createCatalog(ctx, req) {
   return request(ctx, `${VEGA_BASE}/catalogs`, {
     method: "POST",
     body: {
+      ...req.id ? { id: req.id } : {},
       name: req.name,
       connector_type: req.connectorType,
       connector_config: req.connectorConfig,
       ...req.tags ? { tags: req.tags } : {},
       ...req.description ? { description: req.description } : {},
-      ...req.enabled !== void 0 ? { enabled: req.enabled } : {}
+      ...req.enabled !== void 0 ? { enabled: req.enabled } : {},
+      ...req.internal !== void 0 ? { internal: req.internal } : {},
+      ...req.extensions ? { extensions: req.extensions } : {}
+    }
+  });
+}
+function updateCatalog(ctx, id, req) {
+  return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}`, {
+    method: "PUT",
+    body: {
+      ...req.id ? { id: req.id } : {},
+      ...req.name ? { name: req.name } : {},
+      ...req.connectorType ? { connector_type: req.connectorType } : {},
+      ...req.connectorConfig !== void 0 ? { connector_config: req.connectorConfig } : {},
+      ...req.tags ? { tags: req.tags } : {},
+      ...req.description !== void 0 ? { description: req.description } : {},
+      ...req.enabled !== void 0 ? { enabled: req.enabled } : {},
+      ...req.extensions ? { extensions: req.extensions } : {}
     }
   });
 }
 function enableCatalog(ctx, id) {
   return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/enable`, { method: "POST" });
 }
+function disableCatalog(ctx, id) {
+  return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/disable`, {
+    method: "POST"
+  });
+}
+function deleteCatalog(ctx, id) {
+  return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}`, { method: "DELETE" });
+}
+function testCatalogConnection(ctx, id) {
+  return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/test-connection`, {
+    method: "POST"
+  });
+}
 function discoverCatalog(ctx, id, wait = true) {
   return request(ctx, `${VEGA_BASE}/catalogs/${encodeURIComponent(id)}/discover`, {
     method: "POST",
@@ -2910,9 +3344,15 @@ function discoverCatalog(ctx, id, wait = true) {
     timeoutMs: 12e4
   });
 }
-function listCatalogResources(ctx, id, category) {
+function listCatalogResources(ctx, id, category, limit, offset) {
   return request(ctx, `${VEGA_BASE}/resources`, {
-    query: { catalog_id: id, category: category || void 0 }
+    query: {
+      catalog_id: id,
+      category: category || void 0,
+      // limit=-1 (NO_LIMIT) fetches all; NaN / 0 fall back to the backend default.
+      limit: Number.isFinite(limit) && (limit > 0 || limit === -1) ? limit : void 0,
+      offset: offset || void 0
+    }
   });
 }
 function catalogHealthStatus(ctx, ids) {
@@ -3372,7 +3812,7 @@ async function createFromCatalog(ctx, opts) {
     }
     tablePk[t.name] = res.pk;
   }
-  log(`Creating resources for ${targets.length} table(s)...`);
+  log(`Resolving discovered resources for ${targets.length} table(s)...`);
   const viewMap = {};
   for (const t of targets) {
     const found = asArray(
@@ -3382,13 +3822,9 @@ async function createFromCatalog(ctx, opts) {
     if (existingId) {
       viewMap[t.name] = existingId;
     } else {
-      const created = await createResource(ctx, {
-        name: t.name,
-        catalogId: opts.catalogId,
-        sourceIdentifier: t.name,
-        fields: t.columns.map((c) => ({ name: c.name, type: c.type }))
-      });
-      viewMap[t.name] = String(created.id ?? "");
+      throw new Error(
+        `Table '${t.name}' has no discovered Vega resource. Run catalog discover and retry.`
+      );
     }
   }
   const knCreated = await createKnowledgeNetwork(ctx, { name: opts.name });
@@ -3420,12 +3856,14 @@ async function createFromCatalog(ctx, opts) {
       log("Submitting build tasks...");
       for (const t of targets) {
         const embedding = opts.embeddingFields?.[t.name];
+        await configureResourceIndex(ctx, viewMap[t.name], {
+          buildKeyFields: [tablePk[t.name]],
+          ...embedding && embedding.length > 0 ? { embeddingFields: embedding } : {},
+          ...opts.embeddingModel ? { embeddingModel: opts.embeddingModel } : {}
+        });
         const task = await createBuildTask(ctx, {
           resource_id: viewMap[t.name],
-          mode: "batch",
-          build_key_fields: [tablePk[t.name]],
-          ...embedding && embedding.length > 0 ? { embedding_fields: embedding } : {},
-          ...opts.embeddingModel ? { embedding_model: opts.embeddingModel } : {}
+          mode: "batch"
         });
         builds.push({ table: t.name, taskId: String(task.id ?? "") });
       }
@@ -3556,7 +3994,6 @@ function kn(ctx) {
     metricValidate: (knId, body) => validateMetric(ctx, knId, body),
     objectTypes: (knId, opts) => listObjectTypes(ctx, knId, opts),
     objectTypeQuery: (knId, otId, body) => queryObjectTypeInstances(ctx, knId, otId, body),
-    objectTypeProperties: (knId, otId) => getObjectTypeProperties(ctx, knId, otId),
     objectTypeGet: (knId, id) => getSchemaItem(ctx, knId, "object-types", id),
     objectTypeCreate: (knId, body) => createSchemaItem(ctx, knId, "object-types", body),
     objectTypeUpdate: (knId, id, body) => updateSchemaItem(ctx, knId, "object-types", id, body),
@@ -3584,10 +4021,6 @@ function kn(ctx) {
     actionScheduleUpdate: (knId, scheduleId, body) => updateActionSchedule(ctx, knId, scheduleId, body),
     actionScheduleSetStatus: (knId, scheduleId, body) => setActionScheduleStatus(ctx, knId, scheduleId, body),
     actionScheduleDelete: (knId, ids) => deleteActionSchedules(ctx, knId, ids),
-    jobs: (knId) => listJobs(ctx, knId),
-    job: (knId, jobId) => getJob(ctx, knId, jobId),
-    jobTasks: (knId, jobId) => getJobTasks(ctx, knId, jobId),
-    jobDelete: (knId, ids) => deleteJobs(ctx, knId, ids),
     relationTypePaths: (knId, body) => relationTypePaths(ctx, knId, body),
     bknResources: () => listBknResources(ctx),
     createFromCatalog: (opts) => createFromCatalog(ctx, opts),
@@ -3603,12 +4036,19 @@ function kn(ctx) {
       const targets = collectIndexTargets(dir);
       const buildTasks = [];
       for (const t of targets) {
+        if (!t.buildKey) {
+          throw new Error(
+            `Object type '${t.objectType}' declares a vector index but no build key; batch Vega builds require resource index_config.build_key_fields.`
+          );
+        }
+        await configureResourceIndex(ctx, t.resourceId, {
+          buildKeyFields: [t.buildKey],
+          embeddingFields: t.embeddingFields,
+          ...t.embeddingModel ?? opts.embeddingModel ? { embeddingModel: t.embeddingModel ?? opts.embeddingModel } : {}
+        });
         const task = await createBuildTask(ctx, {
           resource_id: t.resourceId,
-          mode: "batch",
-          embedding_fields: t.embeddingFields,
-          ...t.buildKey ? { build_key_fields: [t.buildKey] } : {},
-          ...t.embeddingModel ?? opts.embeddingModel ? { embedding_model: t.embeddingModel ?? opts.embeddingModel } : {}
+          mode: "batch"
         });
         buildTasks.push({
           objectType: t.objectType,
@@ -3663,10 +4103,9 @@ function deltaContent(chunk) {
   return typeof c === "string" ? c : "";
 }
 async function chatCompletionsStream(ctx, model, messages, onDelta) {
-  applyTls(ctx);
   const res = await authFetch(
     ctx,
-    () => fetch(`${ctx.baseUrl}${API}/chat/completions`, {
+    () => tlsFetch(ctx.insecure, `${ctx.baseUrl}${API}/chat/completions`, {
       method: "POST",
       headers: {
         ...buildHeaders(ctx),
@@ -3725,6 +4164,23 @@ function deleteModels(ctx, kind, modelIds) {
 function testModel(ctx, kind, body) {
   return request(ctx, `${MANAGER}/${kind}/test`, { method: "POST", body });
 }
+function setDefaultLlm(ctx, modelId, isDefault = true) {
+  return request(ctx, `${MANAGER}/llm/default/edit`, {
+    method: "POST",
+    body: { model_id: modelId, default: isDefault }
+  });
+}
+function setDefaultSmallModel(ctx, modelId, isDefault = true) {
+  return request(ctx, `${MANAGER}/small-model/set-default`, {
+    method: "POST",
+    body: { model_id: modelId, default: isDefault }
+  });
+}
+function getDefaultSmallModel(ctx, modelType = "embedding") {
+  return request(ctx, `${MANAGER}/small-model/get_default`, {
+    query: { model_type: modelType }
+  });
+}
 function rerank(ctx, model, query, documents) {
   return request(ctx, `${API}/small-model/reranker`, {
     method: "POST",
@@ -3743,7 +4199,9 @@ function models(ctx) {
       add: (body) => addModel(ctx, "llm", body),
       edit: (body) => editModel(ctx, "llm", body),
       delete: (modelIds) => deleteModels(ctx, "llm", modelIds),
-      test: (body) => testModel(ctx, "llm", body)
+      test: (body) => testModel(ctx, "llm", body),
+      /** Set (or clear) the system default LLM. */
+      setDefault: (modelId, isDefault = true) => setDefaultLlm(ctx, modelId, isDefault)
     },
     small: {
       list: (opts) => listSmallModels(ctx, opts),
@@ -3753,7 +4211,11 @@ function models(ctx) {
       add: (body) => addModel(ctx, "small-model", body),
       edit: (body) => editModel(ctx, "small-model", body),
       delete: (modelIds) => deleteModels(ctx, "small-model", modelIds),
-      test: (body) => testModel(ctx, "small-model", body)
+      test: (body) => testModel(ctx, "small-model", body),
+      /** Set (or clear) the system default small model (type inferred from the model). */
+      setDefault: (modelId, isDefault = true) => setDefaultSmallModel(ctx, modelId, isDefault),
+      /** Get the system default small model for a type (default "embedding"). */
+      getDefault: (modelType) => getDefaultSmallModel(ctx, modelType)
     }
   };
 }
@@ -3764,6 +4226,8 @@ function resources(ctx) {
     list: (opts) => listResources2(ctx, opts),
     get: (id) => getResource(ctx, id),
     delete: (id) => deleteResource(ctx, id),
+    update: (id, patch) => updateResource(ctx, id, patch),
+    configureIndex: (id, opts) => configureResourceIndex(ctx, id, opts),
     find: (name, opts) => findResource(ctx, name, opts),
     query: (id, opts) => queryResource(ctx, id, opts)
   };
@@ -3776,7 +4240,6 @@ import { basename as basename2, dirname as dirname3, resolve as resolve5 } from
 // src/api/skills.ts
 var BASE5 = "/api/agent-operator-integration/v1";
 async function registerSkillZip(ctx, bytes, opts = {}) {
-  applyTls(ctx);
   const form2 = new FormData();
   form2.set("file_type", "zip");
   form2.set("file", new Blob([bytes]), opts.filename ?? "skill.zip");
@@ -3784,7 +4247,7 @@ async function registerSkillZip(ctx, bytes, opts = {}) {
   if (opts.extendInfo) form2.set("extend_info", JSON.stringify(opts.extendInfo));
   const res = await authFetch(
     ctx,
-    () => fetch(`${ctx.baseUrl}${BASE5}/skills`, {
+    () => tlsFetch(ctx.insecure, `${ctx.baseUrl}${BASE5}/skills`, {
       method: "POST",
       headers: buildHeaders(ctx),
       body: form2
@@ -3795,13 +4258,12 @@ async function registerSkillZip(ctx, bytes, opts = {}) {
   return text ? JSON.parse(text) : void 0;
 }
 async function updateSkillPackageZip(ctx, skillId, bytes, filename = "skill.zip") {
-  applyTls(ctx);
   const form2 = new FormData();
   form2.set("file_type", "zip");
   form2.set("file", new Blob([bytes]), filename);
   const res = await authFetch(
     ctx,
-    () => fetch(`${ctx.baseUrl}${BASE5}/skills/${encodeURIComponent(skillId)}/package`, {
+    () => tlsFetch(ctx.insecure, `${ctx.baseUrl}${BASE5}/skills/${encodeURIComponent(skillId)}/package`, {
       method: "PUT",
       headers: buildHeaders(ctx),
       body: form2
@@ -3812,10 +4274,9 @@ async function updateSkillPackageZip(ctx, skillId, bytes, filename = "skill.zip"
   return text ? JSON.parse(text) : void 0;
 }
 async function downloadSkill(ctx, skillId) {
-  applyTls(ctx);
   const res = await authFetch(
     ctx,
-    () => fetch(`${ctx.baseUrl}${BASE5}/skills/${encodeURIComponent(skillId)}/download`, {
+    () => tlsFetch(ctx.insecure, `${ctx.baseUrl}${BASE5}/skills/${encodeURIComponent(skillId)}/download`, {
       headers: buildHeaders(ctx)
     })
   );
@@ -3971,25 +4432,27 @@ import { basename as basename3 } from "path";
 var PATH = "/api/agent-operator-integration/v1/tool-box";
 var IMPEX = "/api/agent-operator-integration/v1/impex";
 async function exportConfig(ctx, id, type = "toolbox") {
-  applyTls(ctx);
   const res = await authFetch(
     ctx,
-    () => fetch(`${ctx.baseUrl}${IMPEX}/export/${encodeURIComponent(type)}/${encodeURIComponent(id)}`, {
-      headers: buildHeaders(ctx)
-    })
+    () => tlsFetch(
+      ctx.insecure,
+      `${ctx.baseUrl}${IMPEX}/export/${encodeURIComponent(type)}/${encodeURIComponent(id)}`,
+      {
+        headers: buildHeaders(ctx)
+      }
+    )
   );
   const buf = new Uint8Array(await res.arrayBuffer());
   if (!res.ok) throw new HttpError(res.status, res.statusText, new TextDecoder().decode(buf));
   return buf;
 }
 async function importConfig(ctx, filePath, type = "toolbox") {
-  applyTls(ctx);
   const buf = await readFile2(filePath);
   const form2 = new FormData();
   form2.append("data", new Blob([new Uint8Array(buf)]), basename3(filePath));
   const res = await authFetch(
     ctx,
-    () => fetch(`${ctx.baseUrl}${IMPEX}/import/${encodeURIComponent(type)}`, {
+    () => tlsFetch(ctx.insecure, `${ctx.baseUrl}${IMPEX}/import/${encodeURIComponent(type)}`, {
       method: "POST",
       headers: buildHeaders(ctx),
       body: form2
@@ -4000,14 +4463,13 @@ async function importConfig(ctx, filePath, type = "toolbox") {
   return text ? JSON.parse(text) : text;
 }
 async function uploadTool(ctx, boxId, filePath, metadataType = "openapi") {
-  applyTls(ctx);
   const buf = await readFile2(filePath);
   const form2 = new FormData();
   form2.append("metadata_type", metadataType);
   form2.append("data", new Blob([new Uint8Array(buf)]), basename3(filePath));
   const res = await authFetch(
     ctx,
-    () => fetch(`${ctx.baseUrl}${PATH}/${encodeURIComponent(boxId)}/tool`, {
+    () => tlsFetch(ctx.insecure, `${ctx.baseUrl}${PATH}/${encodeURIComponent(boxId)}/tool`, {
       method: "POST",
       headers: buildHeaders(ctx),
       body: form2
@@ -4022,8 +4484,14 @@ function listToolboxes(ctx, opts = {}) {
     query: { keyword: opts.keyword || void 0, limit: opts.limit, offset: opts.offset ?? 0 }
   });
 }
-function listTools2(ctx, boxId) {
-  return request(ctx, `${PATH}/${encodeURIComponent(boxId)}/tools/list`);
+function listTools2(ctx, boxId, opts = {}) {
+  return request(ctx, `${PATH}/${encodeURIComponent(boxId)}/tools/list`, {
+    query: {
+      page: opts.page,
+      page_size: Number.isFinite(opts.pageSize) && opts.pageSize > 0 ? opts.pageSize : void 0,
+      all: opts.all ? "true" : void 0
+    }
+  });
 }
 function createToolbox(ctx, opts) {
   return request(ctx, PATH, {
@@ -4082,7 +4550,7 @@ function setToolStatuses(ctx, boxId, updates) {
 function toolboxes(ctx) {
   return {
     list: (opts) => listToolboxes(ctx, opts),
-    tools: (boxId) => listTools2(ctx, boxId),
+    tools: (boxId, opts) => listTools2(ctx, boxId, opts),
     create: (opts) => createToolbox(ctx, opts),
     delete: (boxId) => deleteToolbox(ctx, boxId),
     publish: (boxId) => setToolboxStatus(ctx, boxId, "published"),
@@ -4108,8 +4576,728 @@ function toolboxes(ctx) {
   };
 }
 
+// src/trace-session.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var PAYLOAD_FIELDS = {
+  "agent.interaction.started": /* @__PURE__ */ new Set([
+    "intent_hash",
+    "mode",
+    "agent_id",
+    "app_ref",
+    "question_artifact_ref"
+  ]),
+  "retrieval.completed": /* @__PURE__ */ new Set([
+    "query_hash",
+    "candidate_count",
+    "truncated",
+    "version_status",
+    "source_refs"
+  ]),
+  "knowledge.read.observed": /* @__PURE__ */ new Set([
+    "kn_id",
+    "read_kind",
+    "version_status",
+    "schema_version",
+    "business_refs"
+  ]),
+  "data.query.observed": /* @__PURE__ */ new Set([
+    "query_hash",
+    "query_type",
+    "row_count",
+    "truncated",
+    "as_of",
+    "version_status",
+    "resource_refs",
+    "field_refs",
+    "query_artifact_ref",
+    "result_artifact_ref"
+  ]),
+  "logic.execution.observed": /* @__PURE__ */ new Set([
+    "logic_ref",
+    "input_artifact_ref",
+    "result_artifact_ref",
+    "status"
+  ]),
+  "model.call.observed": /* @__PURE__ */ new Set([
+    "model_name",
+    "model_provider",
+    "status",
+    "input_token_count",
+    "output_token_count",
+    "prompt_hash",
+    "output_hash",
+    "error_category",
+    "error_hash"
+  ]),
+  "tool.called": /* @__PURE__ */ new Set(["tool_id", "tool_name", "args_hash", "visibility", "version_status"]),
+  "tool.result.observed": /* @__PURE__ */ new Set([
+    "tool_id",
+    "tool_name",
+    "status",
+    "result_hash",
+    "result_length",
+    "result_count",
+    "error_hash",
+    "error_category",
+    "visibility",
+    "version_status"
+  ]),
+  "claim.created": /* @__PURE__ */ new Set([
+    "claim_id",
+    "claim_type",
+    "claim_hash",
+    "source_event_ids",
+    "operation_ids",
+    "visibility",
+    "version_status",
+    "result_artifact_ref"
+  ]),
+  "evidence.refs.created": /* @__PURE__ */ new Set(["claim_id", "evidence_refs"]),
+  "business.refs.resolved": /* @__PURE__ */ new Set(["claim_id", "resolver_status", "business_refs"]),
+  "action.recommended": /* @__PURE__ */ new Set([
+    "action_instance_id",
+    "action_type",
+    "target_refs",
+    "reason_hash",
+    "status",
+    "reason_artifact_ref",
+    "input_artifact_ref"
+  ]),
+  "action.approval_requested": /* @__PURE__ */ new Set(["action_instance_id", "policy_ref", "status"]),
+  "action.approved": /* @__PURE__ */ new Set(["action_instance_id", "actor_ref", "policy_decision_ref", "status"]),
+  "action.rejected": /* @__PURE__ */ new Set(["action_instance_id", "actor_ref", "policy_decision_ref", "status"]),
+  "action.executed": /* @__PURE__ */ new Set([
+    "action_instance_id",
+    "status",
+    "invocation_ref",
+    "error_category",
+    "error_hash"
+  ]),
+  "action.result_recorded": /* @__PURE__ */ new Set([
+    "action_instance_id",
+    "status",
+    "result_hash",
+    "task_ref",
+    "artifact_ref",
+    "result_artifact_ref"
+  ])
+};
+var REQUIRED_PAYLOAD_FIELDS = {
+  "agent.interaction.started": ["intent_hash", "mode"],
+  "retrieval.completed": ["query_hash", "candidate_count", "truncated"],
+  "knowledge.read.observed": ["kn_id", "read_kind", "version_status"],
+  "data.query.observed": ["query_hash", "query_type", "row_count"],
+  "logic.execution.observed": ["logic_ref", "input_artifact_ref", "result_artifact_ref", "status"],
+  "model.call.observed": [
+    "model_name",
+    "model_provider",
+    "status",
+    "input_token_count",
+    "output_token_count",
+    "prompt_hash",
+    "output_hash"
+  ],
+  "tool.called": ["tool_id", "tool_name", "args_hash", "visibility", "version_status"],
+  "tool.result.observed": ["tool_id", "tool_name", "status", "visibility", "version_status"],
+  "claim.created": [
+    "claim_id",
+    "claim_type",
+    "claim_hash",
+    "source_event_ids",
+    "operation_ids",
+    "visibility",
+    "version_status"
+  ],
+  "evidence.refs.created": ["claim_id", "evidence_refs"],
+  "business.refs.resolved": ["claim_id", "resolver_status", "business_refs"],
+  "action.recommended": [
+    "action_instance_id",
+    "action_type",
+    "target_refs",
+    "reason_hash",
+    "status"
+  ],
+  "action.approval_requested": ["action_instance_id", "policy_ref", "status"],
+  "action.approved": ["action_instance_id", "actor_ref", "policy_decision_ref", "status"],
+  "action.rejected": ["action_instance_id", "actor_ref", "policy_decision_ref", "status"],
+  "action.executed": ["action_instance_id", "status", "invocation_ref"],
+  "action.result_recorded": ["action_instance_id", "status", "result_hash"]
+};
+var REF_FIELDS = /* @__PURE__ */ new Set([
+  "ref_id",
+  "ref_type",
+  "source_system",
+  "validity",
+  "version_status",
+  "visibility",
+  "summary_hash"
+]);
+var RAW_KEYS = /* @__PURE__ */ new Set([
+  "authorization",
+  "cookie",
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "api_key",
+  "password",
+  "private_key",
+  "prompt",
+  "user_question",
+  "approval_comment",
+  "sql",
+  "query_params",
+  "rows"
+]);
+var HASH_RE = /^sha256:[0-9a-f]{64}$/;
+var RAW_VALUE_PATTERNS = [
+  /bearer\s+[A-Za-z0-9._-]+/i,
+  /\bselect\s+.+\s+from\b/is,
+  /\binsert\s+into\b/i,
+  /\bupdate\s+\S+\s+set\b/i,
+  /\bdelete\s+from\b/i,
+  /[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}/,
+  /https?:\/\/[^\s"']+/i
+];
+function defaultNow() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function assertSessionOptions(options) {
+  const trace2 = options.trace;
+  if (!/^[0-9a-f]{32}$/.test(trace2.trace_id)) throw new Error("trace_id must be 32 hex characters");
+  const traceparent = /^00-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/.exec(trace2.traceparent);
+  if (!traceparent || traceparent[1] !== trace2.trace_id) {
+    throw new Error("traceparent must be valid and match trace_id");
+  }
+  if (!/^req_[0-9A-Za-z_.-]+$/.test(trace2["bkn.request.id"])) {
+    throw new Error("bkn.request.id must start with req_");
+  }
+  const conversationId = options.conversationId ?? trace2["bkn.conversation.id"];
+  if (conversationId && !/^[0-9A-Za-z_.:-]{1,128}$/.test(conversationId)) {
+    throw new Error("conversationId must be an opaque correlation identifier");
+  }
+  if (options.conversationId && trace2["bkn.conversation.id"] && options.conversationId !== trace2["bkn.conversation.id"]) {
+    throw new Error("conversationId conflicts with trace bkn.conversation.id");
+  }
+  if (!trace2["bkn.tenant.id"] && !trace2.business_domain) {
+    throw new Error("trace requires bkn.tenant.id or business_domain");
+  }
+  if (!trace2["bkn.account.id"] || !trace2["bkn.account.type"]) {
+    throw new Error("trace requires account id and type");
+  }
+  if (!/^[0-9a-f]{16}$/.test(options.spanId)) throw new Error("spanId must be 16 hex characters");
+  if (!options.producerModule.trim()) throw new Error("producerModule is required");
+}
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function assertSafePayload(eventType, payload) {
+  const allowed = PAYLOAD_FIELDS[eventType];
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new Error(`${eventType} payload field is not registered: ${key}`);
+  }
+  for (const key of REQUIRED_PAYLOAD_FIELDS[eventType] ?? []) {
+    if (payload[key] === void 0 || payload[key] === "") {
+      throw new Error(`${eventType} payload requires ${key}`);
+    }
+  }
+  if (eventType === "agent.interaction.started" && !payload.agent_id && !payload.app_ref) {
+    throw new Error("agent.interaction.started requires agent_id or app_ref");
+  }
+  if (eventType === "agent.interaction.started") {
+    assertEnum(payload, "mode", ["chat", "task", "background"]);
+  }
+  if (eventType === "model.call.observed" || eventType === "action.executed") {
+    assertEnum(payload, "status", ["ok", "error"]);
+  }
+  if (eventType === "model.call.observed" && payload.status === "error") {
+    for (const key of ["error_category", "error_hash"]) {
+      if (!payload[key]) throw new Error(`model.call.observed error requires ${key}`);
+    }
+  }
+  if (eventType === "tool.result.observed") {
+    assertEnum(payload, "status", ["success", "error"]);
+    if (payload.status === "success" && !payload.result_hash) {
+      throw new Error("tool.result.observed success requires result_hash");
+    }
+    if (payload.status === "error" && !payload.error_hash) {
+      throw new Error("tool.result.observed error requires error_hash");
+    }
+  }
+  if (eventType === "business.refs.resolved") {
+    assertEnum(payload, "resolver_status", ["resolved", "partial", "unresolved"]);
+  }
+  for (const key of ["source_event_ids", "operation_ids", "target_refs"]) {
+    if (key in payload && (!Array.isArray(payload[key]) || payload[key].length === 0)) {
+      throw new Error(`${eventType} payload requires non-empty ${key}`);
+    }
+  }
+  if (eventType === "action.recommended") {
+    for (const ref of payload.target_refs) assertQualifiedReference(ref);
+  }
+  if (eventType === "evidence.refs.created") {
+    assertRefs(payload.evidence_refs, false);
+  }
+  if (eventType === "business.refs.resolved") {
+    const unresolved = payload.resolver_status === "unresolved";
+    assertRefs(payload.business_refs, unresolved);
+  }
+  if (eventType === "action.result_recorded" && !payload.task_ref && !payload.artifact_ref && !payload.result_artifact_ref) {
+    throw new Error(
+      "action.result_recorded requires task_ref, artifact_ref, or result_artifact_ref"
+    );
+  }
+  if (eventType === "action.executed" && payload.status === "error") {
+    for (const key of ["error_category", "error_hash"]) {
+      if (!payload[key]) throw new Error(`action.executed error requires ${key}`);
+    }
+  }
+  const fixedStatus = {
+    "action.recommended": "recommended",
+    "action.approval_requested": "approval_requested",
+    "action.approved": "approved",
+    "action.rejected": "rejected"
+  };
+  if (fixedStatus[eventType] && payload.status !== fixedStatus[eventType]) {
+    throw new Error(`${eventType} requires status=${fixedStatus[eventType]}`);
+  }
+  scanSafeValue(payload, "payload");
+}
+function assertRefs(value, allowEmpty) {
+  if (!Array.isArray(value) || !allowEmpty && value.length === 0) {
+    throw new Error("reference list must be a non-empty array");
+  }
+  for (const item of value) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      throw new Error("reference must be an object");
+    }
+    const ref = item;
+    for (const key of Object.keys(ref)) {
+      if (!REF_FIELDS.has(key)) throw new Error(`reference field is not registered: ${key}`);
+    }
+    for (const key of [
+      "ref_id",
+      "ref_type",
+      "source_system",
+      "validity",
+      "version_status",
+      "visibility"
+    ]) {
+      if (!ref[key]) throw new Error(`reference requires ${key}`);
+    }
+    assertQualifiedReference(String(ref.ref_id));
+    assertEnum(ref, "validity", ["observed", "available", "unavailable", "expired", "partial"]);
+    assertEnum(ref, "version_status", ["versioned", "unversioned", "not_auditable"]);
+    assertEnum(ref, "visibility", [
+      "visible",
+      "redacted",
+      "hidden",
+      "omitted",
+      "unresolved",
+      "unauthorized"
+    ]);
+  }
+}
+function assertQualifiedReference(value) {
+  const parts = value.trim().split(":");
+  const namespace = parts[0] ?? "";
+  let valid = parts.every((part) => part.length > 0);
+  if (["kn", "resource"].includes(namespace)) valid = valid && parts.length === 2;
+  if (["object", "relation", "action_type", "metric", "field"].includes(namespace)) {
+    valid = valid && parts.length === 3;
+  }
+  if (namespace === "property") valid = valid && parts.length === 4;
+  if (!valid) {
+    throw new Error("business reference id must include its knowledge-network or resource scope");
+  }
+}
+function assertEnum(value, key, allowed) {
+  if (!allowed.includes(String(value[key]))) {
+    throw new Error(`${key} must be one of ${allowed.join(", ")}`);
+  }
+}
+function scanSafeValue(value, path) {
+  if (Array.isArray(value)) {
+    value.forEach((child, index) => scanSafeValue(child, `${path}[${index}]`));
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      if (RAW_KEYS.has(key.toLowerCase())) throw new Error(`raw sensitive payload field: ${key}`);
+      if (key.endsWith("_hash") && child !== "" && !HASH_RE.test(String(child))) {
+        throw new Error(`${path}.${key} must be a sha256 hash`);
+      }
+      scanSafeValue(child, `${path}.${key}`);
+    }
+    return;
+  }
+  if (typeof value === "string" && RAW_VALUE_PATTERNS.some((pattern) => pattern.test(value))) {
+    throw new Error(`raw sensitive payload value at ${path}`);
+  }
+}
+var TraceSession = class {
+  interactionId;
+  trace;
+  producerModule;
+  spanId;
+  emit;
+  contractVersion;
+  idFactory;
+  now;
+  events = [];
+  eventIDs = /* @__PURE__ */ new Set();
+  operationIDs = /* @__PURE__ */ new Set();
+  claimEventIDs = /* @__PURE__ */ new Map();
+  actions = /* @__PURE__ */ new WeakMap();
+  flushTail = Promise.resolve();
+  constructor(options) {
+    assertSessionOptions(options);
+    this.trace = clone(options.trace);
+    if (options.conversationId) {
+      this.trace["bkn.conversation.id"] = options.conversationId;
+    }
+    this.producerModule = options.producerModule;
+    this.spanId = options.spanId;
+    this.emit = options.emit;
+    this.contractVersion = options.contractVersion ?? "2.1.0";
+    this.idFactory = options.idFactory ?? randomUUID2;
+    this.now = options.now ?? defaultNow;
+    this.interactionId = options.interactionId ?? this.idFactory();
+  }
+  startInteraction(input) {
+    return this.append("agent.interaction.started", {
+      operationName: input.operationName,
+      payload: {
+        intent_hash: input.intentHash,
+        mode: input.mode,
+        ...input.agentId ? { agent_id: input.agentId } : {},
+        ...input.appRef ? { app_ref: input.appRef } : {},
+        ...input.questionArtifactRef ? { question_artifact_ref: input.questionArtifactRef } : {}
+      }
+    });
+  }
+  observeOperation(eventType, input) {
+    const operationId = input.operationId ?? this.idFactory();
+    this.operationIDs.add(operationId);
+    return this.append(eventType, { ...input, operationId });
+  }
+  createClaim(input) {
+    if (input.sourceEventIds.length === 0 || input.operationIds.length === 0) {
+      throw new Error("claim requires at least one source event and operation");
+    }
+    this.assertKnownRefs(input.sourceEventIds, this.eventIDs, "event");
+    this.assertKnownRefs(input.operationIds, this.operationIDs, "operation");
+    const event = this.append("claim.created", {
+      operationName: input.operationName,
+      causationEventId: input.causationEventId,
+      claimId: input.claimId,
+      payload: {
+        claim_id: input.claimId,
+        claim_type: input.claimType,
+        claim_hash: input.claimHash,
+        source_event_ids: input.sourceEventIds,
+        operation_ids: input.operationIds,
+        visibility: input.visibility ?? "visible",
+        version_status: input.versionStatus ?? "unversioned",
+        ...input.resultArtifactRef ? { result_artifact_ref: input.resultArtifactRef } : {}
+      }
+    });
+    this.claimEventIDs.set(input.claimId, event.event_id);
+    return event;
+  }
+  createEvidenceRefs(input) {
+    const claimEventID = this.requireClaim(input.claimId);
+    if (input.refs.length === 0) throw new Error("evidence refs must not be empty");
+    const operationId = this.idFactory();
+    this.operationIDs.add(operationId);
+    const event = this.append("evidence.refs.created", {
+      operationName: input.operationName,
+      operationId,
+      causationEventId: input.causationEventId ?? claimEventID,
+      claimId: input.claimId,
+      payload: {
+        claim_id: input.claimId,
+        evidence_refs: input.refs.map((ref) => ({
+          ref_id: ref.refId,
+          ref_type: ref.refType,
+          source_system: ref.sourceSystem,
+          validity: ref.validity,
+          version_status: ref.versionStatus,
+          visibility: ref.visibility,
+          ...ref.summaryHash ? { summary_hash: ref.summaryHash } : {}
+        }))
+      }
+    });
+    this.claimEventIDs.set(input.claimId, event.event_id);
+    return event;
+  }
+  resolveBusinessRefs(input) {
+    const claimEventID = this.requireClaim(input.claimId);
+    if (input.resolverStatus === "resolved" && input.refs.length === 0) {
+      throw new Error("resolved business refs must not be empty");
+    }
+    const operationId = this.idFactory();
+    this.operationIDs.add(operationId);
+    const event = this.append("business.refs.resolved", {
+      operationName: input.operationName,
+      operationId,
+      causationEventId: input.causationEventId ?? claimEventID,
+      claimId: input.claimId,
+      payload: {
+        claim_id: input.claimId,
+        resolver_status: input.resolverStatus,
+        business_refs: input.refs.map((ref) => ({
+          ref_id: ref.refId,
+          ref_type: ref.refType,
+          source_system: ref.sourceSystem,
+          validity: ref.validity,
+          version_status: ref.versionStatus,
+          visibility: ref.visibility
+        }))
+      }
+    });
+    this.claimEventIDs.set(input.claimId, event.event_id);
+    return event;
+  }
+  recommendAction(input) {
+    const claimEventID = this.requireClaim(input.claimId);
+    if (input.targetRefs.length === 0) throw new Error("action target refs must not be empty");
+    const operationId = this.idFactory();
+    const actionInstanceId = this.idFactory();
+    this.operationIDs.add(operationId);
+    const event = this.append("action.recommended", {
+      operationName: input.operationName,
+      operationId,
+      causationEventId: input.causationEventId ?? claimEventID,
+      claimId: input.claimId,
+      payload: {
+        action_instance_id: actionInstanceId,
+        action_type: input.actionType,
+        target_refs: input.targetRefs,
+        reason_hash: input.reasonHash,
+        ...input.reasonArtifactRef ? { reason_artifact_ref: input.reasonArtifactRef } : {},
+        ...input.inputArtifactRef ? { input_artifact_ref: input.inputArtifactRef } : {},
+        status: "recommended"
+      }
+    });
+    const internal = {
+      actionInstanceId,
+      claimId: input.claimId,
+      operationId,
+      lastEventId: event.event_id,
+      state: "recommended"
+    };
+    const handle = Object.freeze({
+      get actionInstanceId() {
+        return internal.actionInstanceId;
+      },
+      get claimId() {
+        return internal.claimId;
+      },
+      get operationId() {
+        return internal.operationId;
+      },
+      get lastEventId() {
+        return internal.lastEventId;
+      },
+      get state() {
+        return internal.state;
+      }
+    });
+    this.actions.set(handle, internal);
+    return handle;
+  }
+  requestActionApproval(action, input) {
+    const internal = this.expectActionState(action, "recommended");
+    const event = this.appendAction(internal, "action.approval_requested", {
+      action_instance_id: internal.actionInstanceId,
+      policy_ref: input.policyRef,
+      status: "approval_requested"
+    });
+    internal.state = "approval_requested";
+    internal.lastEventId = event.event_id;
+    return event;
+  }
+  approveAction(action, input) {
+    const internal = this.expectActionState(action, "approval_requested");
+    const event = this.appendAction(internal, "action.approved", {
+      action_instance_id: internal.actionInstanceId,
+      actor_ref: input.actorRef,
+      policy_decision_ref: input.policyDecisionRef,
+      status: "approved"
+    });
+    internal.state = "approved";
+    internal.lastEventId = event.event_id;
+    return event;
+  }
+  rejectAction(action, input) {
+    const internal = this.expectActionState(action, "approval_requested");
+    const event = this.appendAction(internal, "action.rejected", {
+      action_instance_id: internal.actionInstanceId,
+      actor_ref: input.actorRef,
+      policy_decision_ref: input.policyDecisionRef,
+      status: "rejected"
+    });
+    internal.state = "rejected";
+    internal.lastEventId = event.event_id;
+    return event;
+  }
+  executeAction(action, input) {
+    const internal = this.expectActionState(
+      action,
+      "approved",
+      "requires approval before execution"
+    );
+    const event = this.appendAction(internal, "action.executed", {
+      action_instance_id: internal.actionInstanceId,
+      status: input.status,
+      invocation_ref: input.invocationRef,
+      ...input.status === "error" ? { error_category: input.errorCategory, error_hash: input.errorHash } : {}
+    });
+    internal.state = "executed";
+    internal.lastEventId = event.event_id;
+    return event;
+  }
+  recordActionResult(action, input) {
+    const internal = this.expectActionState(action, "executed");
+    const event = this.appendAction(internal, "action.result_recorded", {
+      action_instance_id: internal.actionInstanceId,
+      result_hash: input.resultHash,
+      status: input.status,
+      ...input.taskRef ? { task_ref: input.taskRef } : {},
+      ...input.artifactRef ? { artifact_ref: input.artifactRef } : {},
+      ...input.resultArtifactRef ? { result_artifact_ref: input.resultArtifactRef } : {}
+    });
+    internal.state = "result_recorded";
+    internal.lastEventId = event.event_id;
+    return event;
+  }
+  pendingEvents() {
+    return clone(this.events);
+  }
+  flush() {
+    const requestedIDs = new Set(this.events.map((event) => event.event_id));
+    const operation = this.flushTail.then(() => this.flushEvents(requestedIDs));
+    this.flushTail = operation.then(
+      () => void 0,
+      () => void 0
+    );
+    return operation;
+  }
+  appendAction(action, eventType, payload) {
+    return this.append(eventType, {
+      operationName: eventType,
+      operationId: action.operationId,
+      causationEventId: action.lastEventId,
+      claimId: action.claimId,
+      payload
+    });
+  }
+  append(eventType, input) {
+    assertSafePayload(eventType, input.payload);
+    this.assertContractPayload(eventType, input.payload);
+    if (eventType !== "agent.interaction.started") {
+      if (!input.causationEventId) throw new Error(`${eventType} requires causation_event_id`);
+      if (!this.eventIDs.has(input.causationEventId)) {
+        throw new Error(`unknown event reference: ${input.causationEventId}`);
+      }
+    }
+    if (eventType !== "agent.interaction.started" && eventType !== "claim.created" && !input.operationId) {
+      throw new Error(`${eventType} requires operation_id`);
+    }
+    const eventID = this.idFactory();
+    if (this.eventIDs.has(eventID)) throw new Error(`duplicate event id: ${eventID}`);
+    const timestamp = this.now();
+    const event = {
+      event_id: eventID,
+      event_type: eventType,
+      "bkn.trace.schema.version": this.contractVersion,
+      observed_at: timestamp,
+      emitted_at: timestamp,
+      producer_module: this.producerModule,
+      trace_id: this.trace.trace_id,
+      span_id: this.spanId,
+      "bkn.request.id": this.trace["bkn.request.id"],
+      "bkn.operation.name": input.operationName,
+      interaction_id: this.interactionId,
+      ...input.operationId ? { operation_id: input.operationId } : {},
+      ...input.causationEventId ? { causation_event_id: input.causationEventId } : {},
+      ...input.claimId ? { claim_id: input.claimId } : {},
+      ...input.attempt ? { attempt: input.attempt } : {},
+      payload: clone(input.payload)
+    };
+    this.events.push(clone(event));
+    this.eventIDs.add(eventID);
+    return clone(event);
+  }
+  async flushEvents(requestedIDs) {
+    const batch = this.events.filter((event) => requestedIDs.has(event.event_id));
+    if (batch.length === 0) return void 0;
+    const response = await this.emit({
+      "bkn.trace.schema.version": this.contractVersion,
+      trace: clone(this.trace),
+      events: clone(batch)
+    });
+    const remaining = this.events.filter((event) => !requestedIDs.has(event.event_id));
+    this.events.splice(0, this.events.length, ...remaining);
+    return response;
+  }
+  assertContractPayload(eventType, payload) {
+    if (this.contractVersion !== "2.2.0") return;
+    const requiredArtifactFields = {
+      "agent.interaction.started": ["question_artifact_ref"],
+      "data.query.observed": ["query_artifact_ref", "result_artifact_ref"],
+      "logic.execution.observed": ["input_artifact_ref", "result_artifact_ref"],
+      "claim.created": ["result_artifact_ref"],
+      "action.recommended": ["input_artifact_ref"],
+      "action.result_recorded": ["result_artifact_ref"]
+    };
+    for (const field of requiredArtifactFields[eventType] ?? []) {
+      const value = payload[field];
+      if (typeof value !== "string" || !/^artifact:[0-9A-Za-z][0-9A-Za-z_.:-]{0,127}$/.test(value)) {
+        throw new Error(`${eventType} payload requires valid ${field}`);
+      }
+    }
+    for (const [field, value] of Object.entries(payload)) {
+      if (field.endsWith("_artifact_ref") && value !== void 0) {
+        if (typeof value !== "string" || !/^artifact:[0-9A-Za-z][0-9A-Za-z_.:-]{0,127}$/.test(value)) {
+          throw new Error(`${eventType} payload requires valid ${field}`);
+        }
+      }
+    }
+    if (eventType === "action.result_recorded" && payload.artifact_ref !== void 0) {
+      throw new Error("action.result_recorded 2.2 does not accept legacy artifact_ref");
+    }
+  }
+  assertKnownRefs(values, known, kind) {
+    for (const value of values) {
+      if (!known.has(value)) throw new Error(`unknown ${kind} reference: ${value}`);
+    }
+  }
+  requireClaim(claimID) {
+    const eventID = this.claimEventIDs.get(claimID);
+    if (!eventID) throw new Error(`unknown claim reference: ${claimID}`);
+    return eventID;
+  }
+  expectActionState(action, expected, message) {
+    const internal = this.actions.get(action);
+    if (!internal) throw new Error("action handle does not belong to this trace session");
+    if (internal.state !== expected) {
+      if (message) throw new Error(`action ${internal.actionInstanceId} ${message}`);
+      throw new Error(
+        `action ${internal.actionInstanceId} must be ${expected}, got ${internal.state}`
+      );
+    }
+    return internal;
+  }
+};
+
 // src/api/trace.ts
 var SEARCH = "/api/agent-observability/v1/traces/_search";
+var EVIDENCE_EVENTS = "/api/agent-observability/v1/evidence/events";
+var EVIDENCE_ARTIFACTS = "/api/agent-observability/v1/evidence/artifacts";
+var REQUESTS = "/api/agent-observability/v1/requests";
+var INTERACTIONS = "/api/agent-observability/v1/interactions";
+var TRACES = "/api/agent-observability/v1/traces";
 function isoToNanos(iso) {
   const ms = Date.parse(iso);
   if (Number.isNaN(ms)) return void 0;
@@ -4151,6 +5339,67 @@ async function getRawSpansByConversation(ctx, conversationId, opts = {}) {
 function traceSearch(ctx, body) {
   return request(ctx, SEARCH, { method: "POST", body });
 }
+function emitEvidenceEvents(ctx, body) {
+  return request(ctx, EVIDENCE_EVENTS, {
+    method: "POST",
+    body,
+    headers: evidenceWriteHeaders(ctx),
+    redirect: "manual"
+  });
+}
+function emitEvidenceArtifact(ctx, body) {
+  return request(ctx, EVIDENCE_ARTIFACTS, {
+    method: "POST",
+    body,
+    headers: evidenceWriteHeaders(ctx),
+    redirect: "manual"
+  });
+}
+function evidenceWriteHeaders(ctx) {
+  return ctx.evidenceIngestToken ? { "x-bkn-trace-ingest-token": ctx.evidenceIngestToken } : void 0;
+}
+function getEvidenceArtifact(ctx, artifactId) {
+  return request(ctx, `${EVIDENCE_ARTIFACTS}/${encodeURIComponent(artifactId)}`);
+}
+function listRequestSummaries(ctx, query = {}) {
+  return request(ctx, REQUESTS, {
+    query: summaryQuery(query)
+  });
+}
+function getRequestSummary(ctx, requestId) {
+  return request(ctx, `${REQUESTS}/${encodeURIComponent(requestId)}`);
+}
+function getInteractionSummary(ctx, interactionId) {
+  return request(ctx, `${INTERACTIONS}/${encodeURIComponent(interactionId)}`);
+}
+function getRequestTraces(ctx, requestId, query = {}) {
+  return request(
+    ctx,
+    `${REQUESTS}/${encodeURIComponent(requestId)}/traces`,
+    { query: summaryQuery(query) }
+  );
+}
+function getTraceGraph(ctx, traceId) {
+  return request(ctx, `${TRACES}/${encodeURIComponent(traceId)}/trace-graph`);
+}
+function getEvidenceChain(ctx, scope, opts = {}) {
+  const target = traceTarget(scope, "evidence-chain");
+  return request(ctx, target.path, {
+    query: queryWithLimit(target.query, opts)
+  });
+}
+function getBusinessGraph(ctx, scope, opts = {}) {
+  const target = traceTarget(scope, "business-graph");
+  return request(ctx, target.path, {
+    query: queryWithLimit(target.query, opts)
+  });
+}
+function getSnapshotPreview(ctx, scope, opts = {}) {
+  const target = traceTarget(scope, "snapshot-preview");
+  return request(ctx, target.path, {
+    query: queryWithLimit(target.query, opts)
+  });
+}
 async function getSpansByConversation(ctx, conversationId, opts = {}) {
   const agg = await request(ctx, SEARCH, {
     method: "POST",
@@ -4175,8 +5424,40 @@ async function getSpansByConversation(ctx, conversationId, opts = {}) {
   }) ?? {};
   return (spans.hits?.hits ?? []).map((h) => h._source ?? {});
 }
+function traceTarget(scope, subresource) {
+  if (typeof scope === "string") {
+    return { path: `${TRACES}/${encodeURIComponent(scope)}/${subresource}` };
+  }
+  if ("traceId" in scope) {
+    return { path: `${TRACES}/${encodeURIComponent(scope.traceId)}/${subresource}` };
+  }
+  const requestPath = subresource === "evidence-chain" ? `${TRACES}/by-request` : `${TRACES}/by-request/${subresource}`;
+  return { path: requestPath, query: { request_id: scope.requestId } };
+}
+function queryWithLimit(query, opts) {
+  if (opts.limit === void 0 || !Number.isFinite(opts.limit)) return query;
+  return { ...query ?? {}, limit: opts.limit };
+}
+function summaryQuery(query) {
+  const result = {};
+  if (query.limit !== void 0 && Number.isFinite(query.limit)) result.limit = query.limit;
+  if (query.cursor) result.cursor = query.cursor;
+  if (query.from) result.from = query.from;
+  if (query.to) result.to = query.to;
+  if (query.status) result.status = query.status;
+  if (query.agentOrApp) result.agent_or_app = query.agentOrApp;
+  if (query.businessDomain) result.business_domain = query.businessDomain;
+  if (query.conversationId) result.conversation_id = query.conversationId;
+  if (query.interactionId) result.interaction_id = query.interactionId;
+  if (query.knowledgeNetwork) result.knowledge_network = query.knowledgeNetwork;
+  if (query.evidenceCompleteness) {
+    result.evidence_completeness = query.evidenceCompleteness;
+  }
+  if (query.keyword) result.keyword = query.keyword;
+  return Object.keys(result).length ? result : void 0;
+}
 
-// src/trace-ai/claude-judge.ts
+// src/bkn-trace/claude-judge.ts
 import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
 var ClaudeJudgeError = class extends Error {
   constructor(message, reason) {
@@ -4236,10 +5517,10 @@ async function judgeJson(prompt, opts = {}) {
     child.stdout.on("data", (d) => {
       out += d;
     });
-    child.on("error", (err) => {
+    child.on("error", (err2) => {
       clearTimeout(killer);
       reject(
-        err.code === "ENOENT" ? new ClaudeJudgeError("`claude` not found on PATH", "not_available") : err
+        err2.code === "ENOENT" ? new ClaudeJudgeError("`claude` not found on PATH", "not_available") : err2
       );
     });
     child.on("close", (code) => {
@@ -4249,8 +5530,8 @@ async function judgeJson(prompt, opts = {}) {
       if (code !== 0) return reject(new ClaudeJudgeError(`claude exited ${code}`, "exit"));
       resolve7(out);
     });
-    child.stdin.on("error", (err) => {
-      if (err.code !== "EPIPE") reject(err);
+    child.stdin.on("error", (err2) => {
+      if (err2.code !== "EPIPE") reject(err2);
     });
     child.stdin.end(prompt);
   });
@@ -4258,7 +5539,7 @@ async function judgeJson(prompt, opts = {}) {
   return JSON.parse(extractJsonObject(text));
 }
 
-// src/trace-ai/diagnose.ts
+// src/bkn-trace/diagnose.ts
 var KIND_MAP = {
   chat: "llm",
   text_completion: "llm",
@@ -4652,7 +5933,7 @@ function renderReportMarkdown(r) {
   return lines.join("\n");
 }
 
-// src/trace-ai/eval-set.ts
+// src/bkn-trace/eval-set.ts
 function hashId(s) {
   let h = 5381;
   for (let i = 0; i < s.length; i++) h = h * 33 ^ s.charCodeAt(i);
@@ -4800,6 +6081,747 @@ async function runEvalSet(agentId, cases, deps) {
   };
 }
 
+// src/bkn-trace/fixture-validate.ts
+import { readFileSync as readFileSync4, readdirSync as readdirSync5, statSync as statSync4 } from "fs";
+import { join as join4 } from "path";
+var CONTRACT_VERSIONS = /* @__PURE__ */ new Set(["1.0.0", "2.0.0", "2.1.0"]);
+var BUSINESS_CONTRACT_VERSION = "2.1.0";
+var TRACEPARENT_RE2 = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+var REQUEST_ID_RE2 = /^req_[0-9A-Za-z_.-]+$/;
+var RFC3339_NANO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
+var ALLOWED_BAGGAGE2 = /* @__PURE__ */ new Set(["bkn.account.type", "bkn.runtime.env"]);
+var REQUIRED_LOG_FIELDS = [
+  "trace_id",
+  "span_id",
+  "bkn.request.id",
+  "bkn.module.name",
+  "bkn.operation.name",
+  "bkn.status",
+  "bkn.timestamp",
+  "bkn.trace.schema.version"
+];
+var REQUIRED_SPAN_FIELDS = [
+  "span_id",
+  "name",
+  "bkn.module.name",
+  "bkn.operation.name",
+  "bkn.status",
+  "bkn.timestamp"
+];
+var REQUIRED_EVENT_FIELDS = [
+  "trace_id",
+  "span_id",
+  "bkn.request.id",
+  "bkn.operation.name",
+  "event_id",
+  "event_type",
+  "bkn.trace.schema.version",
+  "observed_at",
+  "emitted_at",
+  "producer_module",
+  "payload"
+];
+var SENSITIVE_PATTERNS = [
+  /authorization/i,
+  /bearer\s+[A-Za-z0-9._-]+/i,
+  /access[_-]?token/i,
+  /api[_-]?key/i,
+  /cookie/i,
+  /\bselect\s+.+\s+from\b/is,
+  /prompt\s*[:=]/i,
+  /https?:\/\/[^\s"']+/i,
+  /[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}/
+];
+var BUSINESS_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "agent.interaction.started",
+  "retrieval.completed",
+  "knowledge.read.observed",
+  "data.query.observed",
+  "model.call.observed",
+  "tool.called",
+  "tool.result.observed",
+  "claim.created",
+  "evidence.refs.created",
+  "business.refs.resolved",
+  "action.recommended",
+  "action.approval_requested",
+  "action.approved",
+  "action.rejected",
+  "action.executed",
+  "action.result_recorded"
+]);
+var CLAIM_EVENT_TYPES = /* @__PURE__ */ new Set([
+  "claim.created",
+  "evidence.refs.created",
+  "business.refs.resolved",
+  "action.recommended",
+  "action.approval_requested",
+  "action.approved",
+  "action.rejected",
+  "action.executed",
+  "action.result_recorded"
+]);
+var ACTION_TRANSITIONS = {
+  recommended: /* @__PURE__ */ new Set(["approval_requested"]),
+  approval_requested: /* @__PURE__ */ new Set(["approved", "rejected"]),
+  approved: /* @__PURE__ */ new Set(["executed"]),
+  executed: /* @__PURE__ */ new Set(["result_recorded"]),
+  rejected: /* @__PURE__ */ new Set(),
+  result_recorded: /* @__PURE__ */ new Set()
+};
+var ACTION_STATE_BY_EVENT = {
+  "action.recommended": "recommended",
+  "action.approval_requested": "approval_requested",
+  "action.approved": "approved",
+  "action.rejected": "rejected",
+  "action.executed": "executed",
+  "action.result_recorded": "result_recorded"
+};
+var EVENT_PAYLOAD_FIELDS = {
+  "agent.interaction.started": /* @__PURE__ */ new Set(["intent_hash", "mode", "agent_id", "app_ref"]),
+  "retrieval.completed": /* @__PURE__ */ new Set([
+    "query_hash",
+    "candidate_count",
+    "truncated",
+    "version_status",
+    "source_refs"
+  ]),
+  "knowledge.read.observed": /* @__PURE__ */ new Set([
+    "kn_id",
+    "read_kind",
+    "version_status",
+    "schema_version",
+    "business_refs"
+  ]),
+  "data.query.observed": /* @__PURE__ */ new Set([
+    "query_hash",
+    "query_type",
+    "row_count",
+    "truncated",
+    "as_of",
+    "version_status",
+    "resource_refs",
+    "field_refs"
+  ]),
+  "model.call.observed": /* @__PURE__ */ new Set([
+    "model_name",
+    "model_provider",
+    "status",
+    "input_token_count",
+    "output_token_count",
+    "prompt_hash",
+    "output_hash",
+    "error_category",
+    "error_hash"
+  ]),
+  "tool.called": /* @__PURE__ */ new Set(["tool_id", "tool_name", "args_hash", "visibility", "version_status"]),
+  "tool.result.observed": /* @__PURE__ */ new Set([
+    "tool_id",
+    "tool_name",
+    "status",
+    "result_hash",
+    "result_length",
+    "result_count",
+    "error_hash",
+    "error_category",
+    "visibility",
+    "version_status"
+  ]),
+  "claim.created": /* @__PURE__ */ new Set([
+    "claim_id",
+    "claim_type",
+    "claim_hash",
+    "source_event_ids",
+    "operation_ids",
+    "visibility",
+    "version_status"
+  ]),
+  "evidence.refs.created": /* @__PURE__ */ new Set(["claim_id", "evidence_refs"]),
+  "business.refs.resolved": /* @__PURE__ */ new Set(["claim_id", "resolver_status", "business_refs"]),
+  "action.recommended": /* @__PURE__ */ new Set([
+    "action_instance_id",
+    "action_type",
+    "target_refs",
+    "reason_hash",
+    "status"
+  ]),
+  "action.approval_requested": /* @__PURE__ */ new Set(["action_instance_id", "policy_ref", "status"]),
+  "action.approved": /* @__PURE__ */ new Set(["action_instance_id", "actor_ref", "policy_decision_ref", "status"]),
+  "action.rejected": /* @__PURE__ */ new Set(["action_instance_id", "actor_ref", "policy_decision_ref", "status"]),
+  "action.executed": /* @__PURE__ */ new Set([
+    "action_instance_id",
+    "invocation_ref",
+    "tool_ref",
+    "status",
+    "error_category",
+    "error_hash"
+  ]),
+  "action.result_recorded": /* @__PURE__ */ new Set([
+    "action_instance_id",
+    "result_hash",
+    "artifact_ref",
+    "task_ref",
+    "status"
+  ])
+};
+var REFERENCE_FIELDS = /* @__PURE__ */ new Set([
+  "ref_id",
+  "ref_type",
+  "source_system",
+  "validity",
+  "version_status",
+  "visibility",
+  "summary_hash"
+]);
+var FORBIDDEN_RAW_KEYS = /* @__PURE__ */ new Set([
+  "authorization",
+  "cookie",
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "api_key",
+  "password",
+  "private_key",
+  "prompt",
+  "user_question",
+  "approval_comment",
+  "sql",
+  "query_params",
+  "rows"
+]);
+function err(code, path, message) {
+  return { code, path, message };
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function jsonFiles(path) {
+  const stat = statSync4(path);
+  if (stat.isFile()) return [path];
+  return readdirSync5(path).filter((name) => name.endsWith(".json")).sort().map((name) => join4(path, name));
+}
+function validTraceparent(value) {
+  if (typeof value !== "string") return false;
+  const match = TRACEPARENT_RE2.exec(value);
+  if (!match) return false;
+  const [, traceId, spanId] = match;
+  return traceId !== "0".repeat(32) && spanId !== "0".repeat(16);
+}
+function checkRequired(item, fields, basePath, errors) {
+  for (const field of fields) {
+    if (item[field] === void 0 || item[field] === "") {
+      errors.push(
+        err(
+          "BKN_TRACE_REQUIRED_FIELD_MISSING",
+          `${basePath}.${field}`,
+          `missing required field ${field}`
+        )
+      );
+    }
+  }
+}
+function checkTimestamp(value, path, errors) {
+  if (typeof value !== "string" || !RFC3339_NANO_RE.test(value)) {
+    errors.push(err("BKN_TRACE_INVALID_TIMESTAMP", path, "timestamp must be UTC RFC3339Nano"));
+  }
+}
+function checkSensitive(value, path, errors) {
+  if (Array.isArray(value)) {
+    value.forEach((child, index) => checkSensitive(child, `${path}[${index}]`, errors));
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      if (FORBIDDEN_RAW_KEYS.has(key.toLowerCase())) {
+        errors.push(
+          err(
+            "BKN_TRACE_SENSITIVE_VALUE_LEAKED",
+            `${path}.${key}`,
+            "raw sensitive field is forbidden"
+          )
+        );
+      }
+      if (key.endsWith("_hash") && child !== "" && (typeof child !== "string" || !/^sha256:[0-9a-f]{64}$/.test(child))) {
+        errors.push(
+          err("BKN_TRACE_REQUIRED_FIELD_MISSING", `${path}.${key}`, `${key} must be a sha256 hash`)
+        );
+      }
+      checkSensitive(child, `${path}.${key}`, errors);
+    }
+    return;
+  }
+  if (typeof value !== "string") return;
+  if (SENSITIVE_PATTERNS.some((pattern) => pattern.test(value))) {
+    errors.push(
+      err(
+        "BKN_TRACE_SENSITIVE_VALUE_LEAKED",
+        path,
+        "sensitive value must be redacted, hashed, or referenced"
+      )
+    );
+  }
+}
+function validateFixture(data) {
+  const root = asRecord(data);
+  const errors = [];
+  const fixtureId = typeof root.fixture_id === "string" ? root.fixture_id : "<unknown>";
+  const contractVersion = typeof root["bkn.trace.schema.version"] === "string" ? root["bkn.trace.schema.version"] : null;
+  if (!contractVersion) {
+    errors.push(
+      err(
+        "BKN_TRACE_SCHEMA_VERSION_MISSING",
+        "$.bkn.trace.schema.version",
+        "missing contract version"
+      )
+    );
+  } else if (!CONTRACT_VERSIONS.has(contractVersion)) {
+    errors.push(
+      err(
+        "BKN_TRACE_SCHEMA_VERSION_UNSUPPORTED",
+        "$.bkn.trace.schema.version",
+        `unsupported contract version ${contractVersion}`
+      )
+    );
+  }
+  const trace2 = asRecord(root.trace);
+  const traceId = trace2.trace_id;
+  const requestId = trace2["bkn.request.id"];
+  if (typeof traceId !== "string" || !/^[0-9a-f]{32}$/.test(traceId)) {
+    errors.push(
+      err("BKN_TRACE_REQUIRED_FIELD_MISSING", "$.trace.trace_id", "missing valid trace id")
+    );
+  }
+  if (typeof requestId !== "string" || !REQUEST_ID_RE2.test(requestId)) {
+    errors.push(
+      err(
+        "BKN_TRACE_REQUIRED_FIELD_MISSING",
+        "$.trace.bkn.request.id",
+        "missing valid bkn.request.id"
+      )
+    );
+  }
+  if (!validTraceparent(trace2.traceparent)) {
+    errors.push(err("BKN_TRACE_INVALID_TRACEPARENT", "$.trace.traceparent", "invalid traceparent"));
+  }
+  const spans = Array.isArray(root.spans) ? root.spans : [];
+  const spanIds = /* @__PURE__ */ new Set();
+  spans.forEach((item, index) => {
+    const span = asRecord(item);
+    checkRequired(span, REQUIRED_SPAN_FIELDS, `$.spans[${index}]`, errors);
+    checkTimestamp(span["bkn.timestamp"], `$.spans[${index}].bkn.timestamp`, errors);
+    if (typeof span.span_id === "string") spanIds.add(span.span_id);
+    const parent = span.parent_span_id;
+    if (parent !== null && parent !== void 0 && !spanIds.has(String(parent))) {
+      errors.push(
+        err(
+          "BKN_TRACE_ORPHAN_SPAN",
+          `$.spans[${index}].parent_span_id`,
+          "parent span must appear before child span or be represented as a link"
+        )
+      );
+    }
+  });
+  if (spans.length === 0) {
+    errors.push(err("BKN_TRACE_REQUIRED_FIELD_MISSING", "$.spans", "at least one span required"));
+  }
+  const logs = Array.isArray(root.logs) ? root.logs : [];
+  logs.forEach((item, index) => {
+    const log = asRecord(item);
+    checkRequired(log, REQUIRED_LOG_FIELDS, `$.logs[${index}]`, errors);
+    checkTimestamp(log["bkn.timestamp"], `$.logs[${index}].bkn.timestamp`, errors);
+    if (log.trace_id !== traceId || log["bkn.request.id"] !== requestId) {
+      errors.push(
+        err("BKN_TRACE_JOIN_FAILED", `$.logs[${index}]`, "log cannot join trace/request")
+      );
+    }
+    if (!spanIds.has(String(log.span_id))) {
+      errors.push(
+        err("BKN_TRACE_JOIN_FAILED", `$.logs[${index}].span_id`, "log span_id not found")
+      );
+    }
+  });
+  const events = Array.isArray(root.events) ? root.events : [];
+  const eventIds = /* @__PURE__ */ new Set();
+  const knownEventIds = /* @__PURE__ */ new Set();
+  const knownOperationIds = /* @__PURE__ */ new Set();
+  const knownClaimIds = /* @__PURE__ */ new Set();
+  const actionStates = /* @__PURE__ */ new Map();
+  events.forEach((item, index) => {
+    const event = asRecord(item);
+    const eventPath = `$.events[${index}]`;
+    checkRequired(event, REQUIRED_EVENT_FIELDS, `$.events[${index}]`, errors);
+    checkTimestamp(event.observed_at, `$.events[${index}].observed_at`, errors);
+    checkTimestamp(event.emitted_at, `$.events[${index}].emitted_at`, errors);
+    if (event.trace_id !== traceId || event["bkn.request.id"] !== requestId) {
+      errors.push(
+        err("BKN_TRACE_JOIN_FAILED", `$.events[${index}]`, "event cannot join trace/request")
+      );
+    }
+    if (!spanIds.has(String(event.span_id))) {
+      errors.push(
+        err("BKN_TRACE_JOIN_FAILED", `$.events[${index}].span_id`, "event span_id not found")
+      );
+    }
+    if (typeof event.event_id === "string") {
+      if (eventIds.has(event.event_id)) {
+        errors.push(
+          err("BKN_TRACE_EVENT_ID_CONFLICT", `${eventPath}.event_id`, "duplicate event_id")
+        );
+      }
+      eventIds.add(event.event_id);
+    }
+    if (contractVersion !== BUSINESS_CONTRACT_VERSION) return;
+    if (event["bkn.trace.schema.version"] !== contractVersion) {
+      errors.push(
+        err(
+          "BKN_TRACE_SCHEMA_VERSION_UNSUPPORTED",
+          `${eventPath}.bkn.trace.schema.version`,
+          "event contract version must match the fixture envelope"
+        )
+      );
+    }
+    validateBusinessEvent(
+      event,
+      eventPath,
+      knownEventIds,
+      knownOperationIds,
+      knownClaimIds,
+      actionStates,
+      errors
+    );
+    if (typeof event.event_id === "string") knownEventIds.add(event.event_id);
+    if (typeof event.operation_id === "string") knownOperationIds.add(event.operation_id);
+    if (event.event_type === "claim.created" && typeof event.claim_id === "string") {
+      knownClaimIds.add(event.claim_id);
+    }
+  });
+  if (contractVersion !== "1.0.0" && events.length === 0) {
+    errors.push(err("BKN_TRACE_REQUIRED_FIELD_MISSING", "$.events", "at least one event required"));
+  }
+  const baggage = asRecord(root.baggage);
+  for (const key of Object.keys(baggage)) {
+    if (!ALLOWED_BAGGAGE2.has(key)) {
+      errors.push(
+        err(
+          "BKN_TRACE_BAGGAGE_FORBIDDEN_FIELD",
+          `$.baggage.${key}`,
+          `baggage field ${key} is forbidden`
+        )
+      );
+    }
+  }
+  checkSensitive(root, "$", errors);
+  const result = errors.length > 0 ? "fail" : "pass";
+  const expectedResult = root.expected_result === "pass" || root.expected_result === "fail" ? root.expected_result : null;
+  return {
+    fixtureId,
+    result,
+    contractVersion,
+    errors,
+    warnings: [],
+    expectedResult,
+    expectationMatched: expectedResult === null ? result === "pass" : expectedResult === result
+  };
+}
+function validateBusinessEvent(event, path, knownEventIds, knownOperationIds, knownClaimIds, actionStates, errors) {
+  const eventType = typeof event.event_type === "string" ? event.event_type : "";
+  if (!BUSINESS_EVENT_TYPES.has(eventType)) {
+    errors.push(
+      err(
+        "BKN_TRACE_EVENT_TYPE_UNSUPPORTED",
+        `${path}.event_type`,
+        `unsupported event ${eventType}`
+      )
+    );
+    return;
+  }
+  checkRequired(event, ["interaction_id"], path, errors);
+  if (eventType !== "agent.interaction.started" && eventType !== "claim.created") {
+    checkRequired(event, ["operation_id"], path, errors);
+  }
+  if (eventType !== "agent.interaction.started") {
+    checkRequired(event, ["causation_event_id"], path, errors);
+    if (typeof event.causation_event_id === "string" && !knownEventIds.has(event.causation_event_id)) {
+      errors.push(
+        err(
+          "BKN_TRACE_CAUSATION_INVALID",
+          `${path}.causation_event_id`,
+          "causation_event_id must reference an earlier event"
+        )
+      );
+    }
+  }
+  if (CLAIM_EVENT_TYPES.has(eventType)) {
+    checkRequired(event, ["claim_id"], path, errors);
+    if (eventType !== "claim.created" && typeof event.claim_id === "string" && !knownClaimIds.has(event.claim_id)) {
+      errors.push(
+        err(
+          "BKN_TRACE_UNKNOWN_CLAIM_ID",
+          `${path}.claim_id`,
+          "event must reference an earlier claim"
+        )
+      );
+    }
+  }
+  const payload = asRecord(event.payload);
+  checkAllowedKeys(
+    payload,
+    EVENT_PAYLOAD_FIELDS[eventType] ?? /* @__PURE__ */ new Set(),
+    `${path}.payload`,
+    errors
+  );
+  if (eventType === "agent.interaction.started") {
+    checkRequired(payload, ["intent_hash", "mode"], `${path}.payload`, errors);
+    checkOneOf(payload, ["agent_id", "app_ref"], `${path}.payload`, errors);
+  }
+  if (eventType === "retrieval.completed") {
+    checkRequired(
+      payload,
+      ["query_hash", "candidate_count", "truncated"],
+      `${path}.payload`,
+      errors
+    );
+  }
+  if (eventType === "knowledge.read.observed") {
+    checkRequired(payload, ["kn_id", "read_kind", "version_status"], `${path}.payload`, errors);
+  }
+  if (eventType === "data.query.observed") {
+    checkRequired(payload, ["query_hash", "query_type", "row_count"], `${path}.payload`, errors);
+  }
+  if (eventType === "model.call.observed") {
+    checkRequired(
+      payload,
+      [
+        "model_name",
+        "model_provider",
+        "status",
+        "input_token_count",
+        "output_token_count",
+        "prompt_hash",
+        "output_hash"
+      ],
+      `${path}.payload`,
+      errors
+    );
+    if (payload.status === "error") {
+      checkRequired(payload, ["error_category", "error_hash"], `${path}.payload`, errors);
+    }
+  }
+  if (eventType === "claim.created") {
+    checkRequired(
+      payload,
+      [
+        "claim_id",
+        "claim_type",
+        "claim_hash",
+        "source_event_ids",
+        "operation_ids",
+        "visibility",
+        "version_status"
+      ],
+      `${path}.payload`,
+      errors
+    );
+    checkNonEmptyArray(payload, "source_event_ids", `${path}.payload`, errors);
+    checkNonEmptyArray(payload, "operation_ids", `${path}.payload`, errors);
+    checkKnownArray(payload, "source_event_ids", knownEventIds, `${path}.payload`, errors);
+    checkKnownArray(payload, "operation_ids", knownOperationIds, `${path}.payload`, errors);
+  }
+  if (eventType === "evidence.refs.created") {
+    checkReferenceList(payload, "evidence_refs", `${path}.payload`, errors);
+  }
+  if (eventType === "business.refs.resolved") {
+    checkRequired(payload, ["resolver_status"], `${path}.payload`, errors);
+    checkReferenceList(
+      payload,
+      "business_refs",
+      `${path}.payload`,
+      errors,
+      payload.resolver_status === "unresolved"
+    );
+  }
+  const actionState = ACTION_STATE_BY_EVENT[eventType];
+  if (!actionState) return;
+  checkRequired(payload, ["action_instance_id", "status"], `${path}.payload`, errors);
+  const fixedStatus = {
+    "action.recommended": "recommended",
+    "action.approval_requested": "approval_requested",
+    "action.approved": "approved",
+    "action.rejected": "rejected"
+  };
+  if (fixedStatus[eventType] && payload.status !== fixedStatus[eventType]) {
+    errors.push(
+      err(
+        "BKN_TRACE_ACTION_TRANSITION_INVALID",
+        `${path}.payload.status`,
+        `${eventType} requires status=${fixedStatus[eventType]}`
+      )
+    );
+  }
+  if (eventType === "action.recommended") {
+    checkRequired(
+      payload,
+      ["action_type", "target_refs", "reason_hash"],
+      `${path}.payload`,
+      errors
+    );
+    checkNonEmptyArray(payload, "target_refs", `${path}.payload`, errors);
+    checkQualifiedStringRefs(payload, "target_refs", `${path}.payload`, errors);
+  }
+  if (eventType === "action.approval_requested") {
+    checkRequired(payload, ["policy_ref"], `${path}.payload`, errors);
+  }
+  if (eventType === "action.approved" || eventType === "action.rejected") {
+    checkRequired(payload, ["actor_ref", "policy_decision_ref"], `${path}.payload`, errors);
+  }
+  if (eventType === "action.executed") {
+    checkOneOf(payload, ["invocation_ref", "tool_ref"], `${path}.payload`, errors);
+    if (payload.status === "error") {
+      checkRequired(payload, ["error_category", "error_hash"], `${path}.payload`, errors);
+    }
+  }
+  if (eventType === "action.result_recorded") {
+    checkRequired(payload, ["result_hash"], `${path}.payload`, errors);
+    checkOneOf(payload, ["artifact_ref", "task_ref"], `${path}.payload`, errors);
+  }
+  const actionID = typeof payload.action_instance_id === "string" ? payload.action_instance_id : "";
+  if (!actionID) return;
+  const claimID = typeof event.claim_id === "string" ? event.claim_id : "";
+  const operationID = typeof event.operation_id === "string" ? event.operation_id : "";
+  const previous = actionStates.get(actionID);
+  if (!previous && actionState !== "recommended" || previous && (!ACTION_TRANSITIONS[previous.state]?.has(actionState) || event.causation_event_id !== previous.lastEventID || claimID !== previous.claimID || operationID !== previous.operationID)) {
+    errors.push(
+      err(
+        "BKN_TRACE_ACTION_TRANSITION_INVALID",
+        `${path}.event_type`,
+        `invalid action transition ${previous?.state ?? "<none>"} -> ${actionState}`
+      )
+    );
+    return;
+  }
+  actionStates.set(actionID, {
+    state: actionState,
+    claimID,
+    operationID,
+    lastEventID: String(event.event_id ?? "")
+  });
+}
+function checkOneOf(payload, fields, path, errors) {
+  if (fields.some((field) => typeof payload[field] === "string" && payload[field] !== "")) return;
+  errors.push(
+    err(
+      "BKN_TRACE_REQUIRED_FIELD_MISSING",
+      `${path}.${fields[0]}`,
+      `one of ${fields.join(" or ")} is required`
+    )
+  );
+}
+function checkNonEmptyArray(payload, field, path, errors) {
+  if (Array.isArray(payload[field]) && payload[field].length > 0) return;
+  errors.push(
+    err(
+      "BKN_TRACE_REQUIRED_FIELD_MISSING",
+      `${path}.${field}`,
+      `${field} must be a non-empty array`
+    )
+  );
+}
+function checkReferenceList(payload, field, path, errors, allowEmpty = false) {
+  if (!allowEmpty) checkNonEmptyArray(payload, field, path, errors);
+  const refs = Array.isArray(payload[field]) ? payload[field] : [];
+  refs.forEach((value, index) => {
+    const ref = asRecord(value);
+    checkRequired(
+      ref,
+      ["ref_id", "ref_type", "source_system", "validity", "version_status", "visibility"],
+      `${path}.${field}[${index}]`,
+      errors
+    );
+    checkAllowedKeys(ref, REFERENCE_FIELDS, `${path}.${field}[${index}]`, errors);
+    if (typeof ref.ref_id === "string" && !isQualifiedReference(ref.ref_id)) {
+      errors.push(
+        err(
+          "BKN_TRACE_REFERENCE_ID_INVALID",
+          `${path}.${field}[${index}].ref_id`,
+          "business reference id must include its knowledge-network or resource scope"
+        )
+      );
+    }
+  });
+}
+function checkQualifiedStringRefs(payload, field, path, errors) {
+  const refs = Array.isArray(payload[field]) ? payload[field] : [];
+  refs.forEach((value, index) => {
+    if (typeof value !== "string" || isQualifiedReference(value)) return;
+    errors.push(
+      err(
+        "BKN_TRACE_REFERENCE_ID_INVALID",
+        `${path}.${field}[${index}]`,
+        "business reference id must include its knowledge-network or resource scope"
+      )
+    );
+  });
+}
+function isQualifiedReference(value) {
+  const parts = value.trim().split(":");
+  if (parts.some((part) => part.length === 0)) return false;
+  if (["kn", "resource"].includes(parts[0] ?? "")) return parts.length === 2;
+  if (["object", "relation", "action_type", "metric", "field"].includes(parts[0] ?? "")) {
+    return parts.length === 3;
+  }
+  if (parts[0] === "property") return parts.length === 4;
+  return true;
+}
+function checkKnownArray(payload, field, known, path, errors) {
+  if (!Array.isArray(payload[field])) return;
+  for (const value of payload[field]) {
+    if (typeof value === "string" && known.has(value)) continue;
+    errors.push(
+      err(
+        "BKN_TRACE_CAUSATION_INVALID",
+        `${path}.${field}`,
+        `${field} must reference earlier events or operations`
+      )
+    );
+  }
+}
+function checkAllowedKeys(value, allowed, path, errors) {
+  for (const key of Object.keys(value)) {
+    if (allowed.has(key)) continue;
+    errors.push(
+      err(
+        "BKN_TRACE_EVENT_PAYLOAD_FIELD_UNSUPPORTED",
+        `${path}.${key}`,
+        `payload field ${key} is not registered for this event`
+      )
+    );
+  }
+}
+function validateFixturePath(path) {
+  const results = jsonFiles(path).map((file) => {
+    try {
+      return validateFixture(JSON.parse(readFileSync4(file, "utf8")));
+    } catch (e) {
+      return {
+        fixtureId: file,
+        result: "fail",
+        contractVersion: null,
+        errors: [
+          err(
+            "BKN_TRACE_FIXTURE_PARSE_FAILED",
+            "$",
+            `failed to parse JSON: ${e instanceof Error ? e.message : String(e)}`
+          )
+        ],
+        warnings: [],
+        expectedResult: null,
+        expectationMatched: false
+      };
+    }
+  });
+  return { ok: results.every((r) => r.expectationMatched), results };
+}
+
 // src/resources/trace.ts
 async function semanticJudge(question, answer, reference) {
   const prompt = [
@@ -4846,6 +6868,32 @@ function trace(ctx) {
   return {
     /** Raw trace search (OpenSearch-style body). */
     search: (body) => traceSearch(ctx, body),
+    /** Submit BKN Trace phase-two claim/evidence/business events. */
+    emitEvidenceEvents: (body) => emitEvidenceEvents(ctx, body),
+    /** Store one authorized BKN Trace 2.2 business-content artifact. */
+    emitArtifact: (body) => emitEvidenceArtifact(ctx, body),
+    /** Read one authorized BKN Trace 2.2 business-content artifact. */
+    artifact: (artifactId) => getEvidenceArtifact(ctx, artifactId),
+    /** Product-facing business request list and request-to-trace drilldown. */
+    requests: {
+      get: (requestId) => getRequestSummary(ctx, requestId),
+      list: (query) => listRequestSummaries(ctx, query),
+      traces: (requestId, query) => getRequestTraces(ctx, requestId, query)
+    },
+    /** Aggregate all OpenBKN requests and traces for one caller-owned interaction. */
+    interactions: {
+      get: (interactionId) => getInteractionSummary(ctx, interactionId)
+    },
+    /** Create a typed BKN Trace 2.1 session for an Agent or AI application. */
+    createSession: (options) => new TraceSession({ ...options, emit: (body) => emitEvidenceEvents(ctx, body) }),
+    /** Normalized trace tree/status graph by trace id. */
+    graph: (traceId) => getTraceGraph(ctx, traceId),
+    /** Claim -> evidence/business refs graph by trace id or BKN request id. */
+    evidenceChain: (scope, opts) => getEvidenceChain(ctx, scope, opts),
+    /** Business semantic graph by trace id or BKN request id. */
+    businessGraph: (scope, opts) => getBusinessGraph(ctx, scope, opts),
+    /** Metadata-only evidence snapshot preview by trace id or BKN request id. */
+    snapshotPreview: (scope, opts) => getSnapshotPreview(ctx, scope, opts),
     /** All span source docs for a conversation. */
     spans: (conversationId, opts) => getSpansByConversation(ctx, conversationId, opts),
     diagnose: diagnoseOne,
@@ -4883,6 +6931,8 @@ function trace(ctx) {
     },
     /** Build eval cases from a loosely-shaped queries object/array. */
     evalSetBuild: (raw) => buildCasesFromQueries(raw),
+    /** Validate BKN Trace phase-one fixture files or directories. */
+    validateFixture: (path) => validateFixturePath(path),
     /**
      * Run an eval set against an agent: each case's query is sent to the agent,
      * the resulting trace is fetched, and assertions are checked. `llm` enables
@@ -4916,19 +6966,29 @@ function vega(ctx) {
     catalogs: (opts) => listCatalogs(ctx, opts),
     getCatalog: (id) => getCatalog(ctx, id),
     createCatalog: (req) => createCatalog(ctx, req),
+    updateCatalog: (id, req) => updateCatalog(ctx, id, req),
     enableCatalog: (id) => enableCatalog(ctx, id),
+    disableCatalog: (id) => disableCatalog(ctx, id),
+    deleteCatalog: (id) => deleteCatalog(ctx, id),
+    testCatalogConnection: (id) => testCatalogConnection(ctx, id),
     discoverCatalog: (id, wait = false) => discoverCatalog(ctx, id, wait),
-    catalogResources: (id, category) => listCatalogResources(ctx, id, category),
+    catalogResources: (id, category, limit, offset) => listCatalogResources(ctx, id, category, limit, offset),
     catalogHealth: (ids) => catalogHealthStatus(ctx, ids),
     connectorTypes: () => listConnectorTypes(ctx),
     connectorType: (type) => getConnectorType(ctx, type),
+    /** Run SQL / OpenSearch DSL directly against a data source. */
+    sql: (body) => runSql(ctx, body),
     /** Build a resource's index. With `wait`, polls until terminal. */
     build: async (req, opts = {}) => {
       const task = await createBuildTask(ctx, req);
       if (!opts.wait) return task;
       return pollBuildTask(ctx, task.id, opts.timeoutMs ?? 3e5, opts.intervalMs ?? 2e3);
     },
-    buildStatus: (taskId) => getBuildTask(ctx, taskId)
+    buildStatus: (taskId) => getBuildTask(ctx, taskId),
+    buildTasks: (opts) => listBuildTasks(ctx, opts),
+    deleteBuildTasks: (ids, opts) => deleteBuildTasks(ctx, ids, opts),
+    startBuildTask: (taskId, opts) => startBuildTask(ctx, taskId, opts),
+    stopBuildTask: (taskId) => stopBuildTask(ctx, taskId)
   };
 }
 async function pollBuildTask(ctx, taskId, timeoutMs, intervalMs) {
@@ -4946,7 +7006,7 @@ function sleep(ms) {
 }
 
 // src/api/call.ts
-import { readFileSync as readFileSync4 } from "fs";
+import { readFileSync as readFileSync5 } from "fs";
 function parseHeader(raw) {
   const idx = raw.indexOf(":");
   if (idx <= 0) return null;
@@ -4964,7 +7024,6 @@ function resolveUrl(ctx, path) {
   return path.startsWith("http") ? path : `${ctx.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
 }
 async function rawCall(ctx, path, opts = {}) {
-  applyTls(ctx);
   const url = resolveUrl(ctx, path);
   const extra = {};
   for (const h of opts.header ?? []) {
@@ -4976,7 +7035,7 @@ async function rawCall(ctx, path, opts = {}) {
     const fd = new FormData();
     for (const field of opts.form) {
       const [key, value, isFile] = parseFormField(field);
-      if (isFile) fd.append(key, new Blob([readFileSync4(value)]), value.split("/").pop());
+      if (isFile) fd.append(key, new Blob([readFileSync5(value)]), value.split("/").pop());
       else fd.append(key, value);
     }
     body = fd;
@@ -4993,7 +7052,12 @@ async function rawCall(ctx, path, opts = {}) {
   try {
     const res = await authFetch(
       ctx,
-      () => fetch(url, { method, headers: headersFor(), body, signal: controller.signal })
+      () => tlsFetch(ctx.insecure, url, {
+        method,
+        headers: headersFor(),
+        body,
+        signal: controller.signal
+      })
     );
     return { status: res.status, statusText: res.statusText, body: await res.text() };
   } finally {
@@ -5001,6 +7065,53 @@ async function rawCall(ctx, path, opts = {}) {
   }
 }
 
+// src/api/app-keys.ts
+var ME = "/api/safe/v1/me/api-keys";
+var ADMIN2 = "/api/safe/v1/admin/api-keys";
+function listMyApiKeys(ctx) {
+  return request(ctx, ME);
+}
+function createMyApiKey(ctx, input) {
+  return request(ctx, ME, {
+    method: "POST",
+    body: {
+      name: input.name,
+      ...input.expiresAt ? { expires_at: input.expiresAt } : {},
+      ...input.neverExpire ? { never_expire: true } : {}
+    }
+  });
+}
+async function revokeMyApiKey(ctx, id) {
+  await request(ctx, `${ME}/${encodeURIComponent(id)}`, { method: "DELETE" });
+}
+function regenerateMyApiKey(ctx, id) {
+  return request(ctx, `${ME}/${encodeURIComponent(id)}/regenerate`, { method: "POST" });
+}
+function listApiKeysAdmin(ctx, ownerId) {
+  return request(ctx, ADMIN2, { query: { owner_id: ownerId || void 0 } });
+}
+async function revokeApiKeyAdmin(ctx, id) {
+  await request(ctx, `${ADMIN2}/${encodeURIComponent(id)}`, { method: "DELETE" });
+}
+
+// src/resources/app-keys.ts
+function appKeys(ctx) {
+  return {
+    /** List the caller's own keys (no secrets). */
+    list: () => listMyApiKeys(ctx),
+    /** Issue a key — the result's `key` is the plaintext, shown only once. */
+    create: (input) => createMyApiKey(ctx, input),
+    /** Revoke one of the caller's keys (immediate). */
+    revoke: (id) => revokeMyApiKey(ctx, id),
+    /** Rotate a key in place — new plaintext (shown once); old secret dies now. */
+    regenerate: (id) => regenerateMyApiKey(ctx, id),
+    /** Admin: list all keys, or one owner's (adds `owner_user_id`). */
+    adminList: (ownerId) => listApiKeysAdmin(ctx, ownerId),
+    /** Admin: revoke any key. */
+    adminRevoke: (id) => revokeApiKeyAdmin(ctx, id)
+  };
+}
+
 // src/client.ts
 function createClient(opts = {}) {
   const ctx = resolveContext(opts);
@@ -5016,6 +7127,7 @@ function createClient(opts = {}) {
     toolboxes: toolboxes(ctx),
     trace: trace(ctx),
     admin: admin(ctx),
+    appKeys: appKeys(ctx),
     vega: vega(ctx),
     call: (path, callOpts) => rawCall(ctx, path, callOpts)
   };
@@ -5024,7 +7136,6 @@ function createClient(opts = {}) {
 // src/resources/auth.ts
 var auth_exports = {};
 __export(auth_exports, {
-  attachNoAuth: () => attachNoAuth,
   attachToken: () => attachToken,
   currentToken: () => currentToken,
   currentTokenFresh: () => currentTokenFresh,
@@ -5062,7 +7173,8 @@ function attachToken(baseUrl, accessToken, opts = {}) {
     accessToken,
     refreshToken: opts.refreshToken,
     idToken: opts.idToken,
-    tlsInsecure: opts.insecure,
+    // Remember `-k` so a self-signed platform needn't repeat it every command.
+    tlsInsecure: opts.insecure ? true : void 0,
     // Prefer the account the user typed (-u); device tokens carry no username.
     username: opts.username ?? decodeJwt(opts.idToken ?? accessToken)?.preferred_username
   };
@@ -5070,33 +7182,40 @@ function attachToken(baseUrl, accessToken, opts = {}) {
   setActivePlatform(url);
   return { baseUrl: url, userId, username: usernameOf(token) };
 }
-function attachNoAuth(baseUrl, opts = {}) {
-  const url = normalize(baseUrl);
-  writeToken(url, { baseUrl: url, accessToken: "", noAuth: true, tlsInsecure: opts.insecure });
-  setActivePlatform(url);
-  return { baseUrl: url, noAuth: true };
+function targetUser(baseUrl, userOrName) {
+  if (!userOrName) return activeUserId(baseUrl);
+  const id = findUserId(baseUrl, userOrName);
+  if (!id) {
+    const known = usersOfPlatform(baseUrl).map((u) => u.username ?? u.userId).join(", ");
+    throw new InputError(
+      `No saved user '${userOrName}' on ${baseUrl}. Saved: ${known || "(none)"}.`
+    );
+  }
+  return id;
 }
-function status() {
+function status(opts = {}) {
   const baseUrl = activePlatform();
   if (!baseUrl) return { hasToken: false };
-  const token = readToken(baseUrl);
+  const userId = targetUser(baseUrl, opts.user);
+  const token = readToken(baseUrl, userId);
   return {
     baseUrl,
-    userId: activeUserId(baseUrl),
+    userId,
     hasToken: token !== void 0,
     username: usernameOf(token),
     expired: token ? isExpired(decodeJwt(token.accessToken)) : void 0
   };
 }
-function currentToken() {
+function currentToken(opts = {}) {
   const baseUrl = activePlatform();
-  const token = baseUrl ? readToken(baseUrl) : void 0;
+  const token = baseUrl ? readToken(baseUrl, targetUser(baseUrl, opts.user)) : void 0;
   if (!token) throw new InputError("Not logged in. Run `openbkn auth login <url> --token <t>`.");
   return token.accessToken;
 }
-async function currentTokenFresh() {
+async function currentTokenFresh(opts = {}) {
   const baseUrl = activePlatform();
-  const token = baseUrl ? readToken(baseUrl) : void 0;
+  const userId = baseUrl ? targetUser(baseUrl, opts.user) : void 0;
+  const token = baseUrl ? readToken(baseUrl, userId) : void 0;
   if (!baseUrl || !token) {
     throw new InputError("Not logged in. Run `openbkn auth login <url> --token <t>`.");
   }
@@ -5105,22 +7224,27 @@ async function currentTokenFresh() {
   const needsRefresh = decodable ? isExpired(claims) : true;
   if (token.refreshToken && needsRefresh) {
     try {
-      const t = await refreshAccessToken(baseUrl, token.refreshToken);
-      writeToken(baseUrl, {
-        ...token,
-        accessToken: t.accessToken,
-        refreshToken: t.refreshToken ?? token.refreshToken,
-        idToken: t.idToken ?? token.idToken
-      });
+      const t = await refreshAccessToken(baseUrl, token.refreshToken, void 0, opts.insecure);
+      writeToken(
+        baseUrl,
+        {
+          ...token,
+          accessToken: t.accessToken,
+          refreshToken: t.refreshToken ?? token.refreshToken,
+          idToken: t.idToken ?? token.idToken
+        },
+        { setActive: !opts.user }
+      );
       return t.accessToken;
     } catch {
     }
   }
   return token.accessToken;
 }
-function whoami() {
+function whoami(opts = {}) {
   const baseUrl = activePlatform();
-  const token = baseUrl ? readToken(baseUrl) : void 0;
+  const userId = baseUrl ? targetUser(baseUrl, opts.user) : void 0;
+  const token = baseUrl ? readToken(baseUrl, userId) : void 0;
   const claims = decodeJwt(token?.idToken ?? "") ?? decodeJwt(token?.accessToken ?? "");
   if (!claims) {
     throw new InputError(
@@ -5130,7 +7254,7 @@ function whoami() {
   return {
     ...claims,
     baseUrl: baseUrl ?? void 0,
-    userId: baseUrl ? activeUserId(baseUrl) : void 0,
+    userId,
     username: usernameOf(token)
   };
 }
@@ -5194,7 +7318,6 @@ export {
   formatError,
   isHeadless,
   openBrowser,
-  fetchAuthStatus,
   deviceLogin,
   credentialDeviceLogin,
   request,
@@ -5209,6 +7332,7 @@ export {
   writePlatformConfig,
   resolveContext,
   getUserSafe,
+  changePasswordSafe,
   admin,
   agents,
   context,
@@ -5221,11 +7345,12 @@ export {
   skills,
   toolboxes,
   renderReportMarkdown,
+  validateFixturePath,
+  TraceSession,
   trace,
   vega,
   createClient,
   attachToken,
-  attachNoAuth,
   status,
   currentToken,
   currentTokenFresh,
@@ -5238,4 +7363,4 @@ export {
   exportCreds,
   auth_exports
 };
-//# sourceMappingURL=chunk-BFE4SU3V.js.map
+//# sourceMappingURL=chunk-LH3ONZGQ.js.map