@openbkn/bkn-sdk 0.1.1 → 0.1.2

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

@@ -26,38 +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) {
-      const next = err.hint ?? "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 "";
@@ -80,16 +80,29 @@ function truncate(s, n) {
 import { spawn } from "child_process";
 
 // src/api/tls.ts
-import { Agent, fetch as undiciFetch } from "undici";
+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()
   });
 }
@@ -305,11 +318,96 @@ async function credentialDeviceLogin(baseUrl, username, password, opts = {}) {
   );
 }
 
+// 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 {
     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
   };
 }
@@ -335,6 +433,7 @@ async function request(ctx, path, init = {}) {
       ...init.headers
     }),
     body: hasBody ? JSON.stringify(init.body) : void 0,
+    redirect: init.redirect,
     signal: controller.signal
   });
   try {
@@ -588,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 } : {}
   };
 }
@@ -774,12 +880,12 @@ async function importLicenseSafe(ctx, licenseText, opts = {}) {
       method: "POST",
       body: { license: text }
     });
-  } catch (err) {
-    if (err instanceof HttpError) {
-      const stored = storedImport(err.body);
+  } catch (err2) {
+    if (err2 instanceof HttpError) {
+      const stored = storedImport(err2.body);
       if (stored) return stored;
     }
-    throw err;
+    throw err2;
   }
 }
 function storedImport(body) {
@@ -1150,19 +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 {
@@ -1223,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 },
@@ -1233,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,
@@ -1369,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) {
@@ -1425,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
   });
 }
@@ -1459,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) {
@@ -1634,7 +1743,10 @@ function listResources2(ctx, opts = {}) {
       category: opts.category || void 0,
       status: opts.status || void 0,
       database: opts.database || void 0,
-      limit: opts.limit && opts.limit > 0 ? opts.limit : 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,
@@ -1750,18 +1862,31 @@ function deleteResource(ctx, id, opts = {}) {
   });
 }
 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
   });
 }
 
@@ -2999,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"));
@@ -3060,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";
@@ -3227,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) {
@@ -3871,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),
@@ -3899,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),
@@ -4366,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, {
@@ -4426,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"),
@@ -4452,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;
@@ -4495,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",
@@ -4519,6 +5424,38 @@ 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/bkn-trace/claude-judge.ts
 import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
@@ -4580,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) => {
@@ -4593,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);
   });
@@ -5144,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 = [
@@ -5190,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,
@@ -5227,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
@@ -5266,7 +6972,7 @@ function vega(ctx) {
     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),
@@ -5300,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;
@@ -5329,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;
@@ -5639,6 +7345,8 @@ export {
   skills,
   toolboxes,
   renderReportMarkdown,
+  validateFixturePath,
+  TraceSession,
   trace,
   vega,
   createClient,
@@ -5655,4 +7363,4 @@ export {
   exportCreds,
   auth_exports
 };
-//# sourceMappingURL=chunk-NC6DZ2AU.js.map
+//# sourceMappingURL=chunk-LH3ONZGQ.js.map