trazio-telemetry 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# Trazio Telemetry SDK for Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Version 0.3.0 renames the package from `hyperlake-telemetry`; the API is unchanged.
+See [SDK integration and release status](https://github.com/cerebrixos-org/sovereign-telemetry-platform/blob/main/sovereign-telemetry-platform/sdk/README.md).
+
+`trazio-telemetry` sends OTLP/HTTP JSON, attaches application events and
+immutable artifacts, manages tenant-editable pipeline settings, and performs
+scoped event, artifact, video, Run, and evidence-graph investigations. Existing OpenTelemetry users
+should keep their native instrumentation and use this SDK only where run
+context, stable event identity, evaluations, or artifact attachment is needed.
+
+```bash
+npm install trazio-telemetry
+npx trazio-telemetry doctor
+```
+
+```js
+import { Client, Privacy } from "trazio-telemetry";
+
+const client = new Client({
+  baseUrl: "https://us.hyperlake.cloud",
+  protocolToken: process.env.PLATFORM_PROTOCOL_TOKEN,
+  tenantJwt: process.env.TENANT_JWT,
+  privacy: new Privacy({ captureContent: false }),
+});
+
+const run = client.startRun("support-agent", { goalId: "goal-42" });
+await run.withSpan("lookup-account", { kind: "RETRIEVER" }, async () => {});
+run.evaluate("groundedness", { score: 0.97, label: "pass" });
+run.end();
+await client.flush();
+
+const investigation = await client.semanticQuery(
+  "Show critical robot video and related faults from the last 2 hours",
+);
+
+const detection = await client.analyzeLiveFrame("./frame.jpg", {
+  streamSessionId: "camera-session-17",
+  frameId: "frame-42",
+  deviceId: "robot-17",
+});
+```
+
+`analyzeLiveFrame()` uses the immutable model profile pinned to the JWT's
+pipeline. It requires a short-lived JWT with `live:analyze` and `event:ingest`.
+The response is a factual object-detection result; the attached live Rule Packs
+determine whether it becomes an alert or notification.
+
+The SDK derives tenant and pipeline routing from the JWT claims and rejects
+conflicting routing IDs before sending a request. Decoding claims locally is not
+signature verification: the regional service verifies the JWT signature,
+issuer, audience, expiry, permissions, tenant, and pipeline on every request.
+Content capture is disabled by default.
+
+## Reliable semantic queries
+
+`semanticQuery()` first creates a versioned, bounded query plan. The plan can
+target events, artifact/vector search, and the evidence graph, but it cannot set
+a tenant, pipeline, URL, token, SQL fragment, or authorization header. The SDK
+then executes each target against the immutable JWT scope and returns the plan,
+its SHA-256 hash, retrieval method, evidence, and scope provenance.
+
+The built-in `DeterministicSemanticPlanner` recognizes bounded time ranges,
+severity, common source families, media intent, and graph intent without an LLM.
+For richer language, pass `ModelSemanticPlanner({ generateObject, model })`.
+Model output is contract-validated; invalid or unsafe output falls back to the
+deterministic plan. This makes a model an intent parser, never an authority or
+direct query executor.
+
+Artifact and video retrieval uses the platform's configured embedding model and
+vector index. Event retrieval is currently structured plus lexical over a
+bounded recent window. Graph retrieval uses recorded scoped edges. The response
+keeps those signals separate so vector similarity is not represented as proof.
+
+Other helpers include `listEvents`, `searchEvents`, `searchArtifacts`,
+`correlationGraph`, `getArtifactSession`, `downloadArtifact`, `getTelemetry`,
+`openVideo`, `timeline`, `listRuns`, `getRun`, `getTenantConfig`,
+`updateTenantConfig`, protocol-token rotation, and tenant Rule Pack validation,
+dry-run, and publication.

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "trazio-telemetry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Scoped telemetry, artifact, investigation, and semantic-query SDK",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./integrations": {
+      "types": "./src/integrations.d.ts",
+      "import": "./src/integrations.js"
+    },
+    "./semantic-query": {
+      "types": "./src/index.d.ts",
+      "import": "./src/semantic-query.js"
+    }
+  },
+  "bin": {
+    "trazio-telemetry": "src/cli.js"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "check": "node --check src/index.js && node --check src/integrations.js && node --check src/semantic-query.js && node --check src/cli.js",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "Proprietary",
+  "author": "Trazio <vc@hyperlake.cloud>",
+  "homepage": "https://hyperlake.cloud",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cerebrixos-org/sovereign-telemetry-platform.git",
+    "directory": "sovereign-telemetry-platform/sdk/typescript"
+  },
+  "keywords": [
+    "opentelemetry",
+    "otlp",
+    "openinference",
+    "agents",
+    "temporal",
+    "langflow",
+    "semantic-search",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+const required = ["PLATFORM_BASE_URL", "PLATFORM_TENANT_ID", "PLATFORM_PIPELINE_ID"];
+const missing = required.filter((name) => !process.env[name]);
+const hasWrite = Boolean(process.env.PLATFORM_PROTOCOL_TOKEN);
+const hasTenant = Boolean(process.env.TENANT_JWT);
+
+console.log(JSON.stringify({
+  ok: missing.length === 0 && (hasWrite || hasTenant),
+  endpoint: process.env.PLATFORM_BASE_URL ?? null,
+  tenant_id_configured: Boolean(process.env.PLATFORM_TENANT_ID),
+  pipeline_id_configured: Boolean(process.env.PLATFORM_PIPELINE_ID),
+  protocol_token_configured: hasWrite,
+  tenant_jwt_configured: hasTenant,
+  content_capture_default: "disabled",
+  missing,
+}, null, 2));
+
+if (missing.length || (!hasWrite && !hasTenant)) process.exitCode = 1;

package/src/index.d.ts

@@ -0,0 +1,167 @@
+export interface PrivacyOptions {
+  captureContent?: boolean;
+  redactedKeys?: string[];
+  maxStringLength?: number;
+  replacement?: string;
+}
+export interface OperationsSnapshot {
+  schema_version: "1.0";
+  tenant_id: string;
+  pipeline_id: string;
+  region: string;
+  revision: string;
+  generated_at: string;
+  consistency: "eventually_consistent";
+  update_mode: "replace_snapshot";
+  refresh_after_ms: number;
+  coverage: { partial: boolean; counts_are_sampled: boolean; maximum_per_dataset: number };
+  entities: Record<string, unknown>[];
+  incidents: Record<string, unknown>[];
+  observations: Record<string, unknown>[];
+  totals: Record<string, unknown>;
+  rules: Record<string, unknown>;
+  pipeline_health: Record<string, unknown>;
+  availability: Record<string, string>;
+}
+export class Privacy {
+  constructor(options?: PrivacyOptions);
+  sanitize(value: unknown, options?: { content?: boolean }): unknown;
+}
+export function stableEventId(...parts: unknown[]): string;
+export type SemanticTarget = "events" | "artifacts" | "graph";
+export type SemanticMode = "hybrid" | "semantic" | "lexical" | "structured";
+export type Severity = "info" | "low" | "medium" | "high" | "critical";
+export interface SemanticQueryPlan {
+  version: "1.0";
+  question: string;
+  mode: SemanticMode;
+  targets: SemanticTarget[];
+  filters: {
+    source_types: string[];
+    event_types: string[];
+    severities: Severity[];
+    keywords: string[];
+    device_id: string | null;
+    run_id: string | null;
+    session_id: string | null;
+    relationship: string | null;
+    rule_id: string | null;
+    from: string | null;
+    to: string | null;
+  };
+  options: { limit: number; max_scan: number; top_k: number; graph_hops: number };
+  planner: { kind: string; model: string | null };
+  plan_hash: string;
+  planner_error?: string;
+}
+export function normalizeSemanticQuery(input: string | Partial<SemanticQueryPlan>, options?: { question?: string; planner?: { kind?: string; model?: string } }): SemanticQueryPlan;
+export class DeterministicSemanticPlanner {
+  plan(question: string): SemanticQueryPlan;
+}
+export class ModelSemanticPlanner {
+  constructor(options: {
+    generateObject: (request: Record<string, unknown>) => Promise<Partial<SemanticQueryPlan>> | Partial<SemanticQueryPlan>;
+    model?: string;
+    fallback?: { plan(question: string): Promise<SemanticQueryPlan> | SemanticQueryPlan };
+  });
+  plan(question: string): Promise<SemanticQueryPlan>;
+}
+export class Span {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId?: string;
+  setAttribute(key: string, value: unknown, options?: { content?: boolean }): this;
+  addEvent(name: string, attributes?: Record<string, unknown>): this;
+  end(options?: { error?: unknown }): void;
+}
+export class Run {
+  readonly traceId: string;
+  readonly runId: string;
+  startSpan(name: string, options?: { kind?: string; attributes?: Record<string, unknown> }): Span;
+  withSpan<T>(name: string, options: { kind?: string; attributes?: Record<string, unknown> }, operation: (span: Span) => Promise<T> | T): Promise<T>;
+  evaluate(name: string, evaluation: { score: number; label: string; explanation?: string }): void;
+  end(options?: { error?: unknown }): void;
+}
+export interface ClientOptions {
+  baseUrl: string;
+  tenantId: string;
+  pipelineId: string;
+  protocolToken?: string;
+  tenantJwt?: string;
+  serviceName?: string;
+  serviceVersion?: string;
+  environment?: string;
+  privacy?: Privacy;
+  timeoutMs?: number;
+  spoolDirectory?: string;
+  maxSpoolFiles?: number;
+  autoFlushSpans?: number;
+  semanticPlanner?: { plan(question: string): Promise<SemanticQueryPlan> | SemanticQueryPlan };
+}
+export class Client {
+  constructor(options: ClientOptions);
+  startRun(name: string, options?: { runId?: string; goalId?: string; agentId?: string; attributes?: Record<string, unknown> }): Run;
+  startSpan(name: string, options?: { traceId?: string; parentSpanId?: string; attributes?: Record<string, unknown> }): Span;
+  flush(): Promise<void>;
+  recordEvent(event: Record<string, unknown>, options?: { idempotencyKey?: string }): Promise<Record<string, unknown>>;
+  uploadArtifact(path: string, options?: { format?: string; deviceId?: string; goalId?: string; metadata?: Record<string, unknown> }): Promise<Record<string, unknown>>;
+  analyzeLiveFrame(path: string, options: { streamSessionId: string; frameId: string; observedAt?: string; deviceId?: string; runId?: string; goalId?: string; contentType?: "image/jpeg" | "image/png" | "image/webp" }): Promise<Record<string, unknown>>;
+  listNoticeDeliveries(options?: {transport?: "room"|"moq";limit?:number;cursor?:string}): Promise<Record<string,unknown>>;
+  replayNoticeDelivery(input:{notice_id:string;stage:string;reason:string;idempotency_key:string},options?:{transport?:"room"|"moq"}):Promise<Record<string,unknown>>;
+  scope(): { tenant_id: string; pipeline_id: string; subject: string | null; cluster_id: string | null; app_id: string | null };
+  listEvents(options?: { limit?: number; cursor?: string; includeAi?: boolean }): Promise<Record<string, unknown>>;
+  searchEvents(query: string | Partial<SemanticQueryPlan>): Promise<Record<string, unknown>>;
+  searchArtifacts(query: string | Partial<SemanticQueryPlan>): Promise<Record<string, unknown>>;
+  correlationGraph(options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  getArtifactSession(sessionId: string): Promise<Record<string, unknown>>;
+  getTelemetry(sessionId: string): Promise<string>;
+  downloadArtifact(sessionId: string): Promise<Uint8Array>;
+  openVideo(sessionId: string, options?: { title?: string; ttlSeconds?: number; embedOrigin?: string }): Promise<Record<string, unknown>>;
+  renewPlayback(sessionId: string, token: string): Promise<Record<string, unknown>>;
+  createLiveEmbed(options: {embed_origin: string; ttl_seconds?: number; tracks?: string[]; stream_session_id?: string}): Promise<Record<string, unknown>>;
+  renewLiveEmbed(grantId: string): Promise<Record<string, unknown>>;
+  revokeLiveEmbed(grantId: string): Promise<Record<string, unknown>>;
+  revokePlayback(sessionId: string, token: string): Promise<Record<string, unknown>>;
+  requestVideoExport(sessionId: string, options: {startSeconds: number; endSeconds: number; idempotencyKey: string}): Promise<Record<string, unknown>>;
+  getVideoExport(sessionId: string, exportId: string): Promise<Record<string, unknown>>;
+  downloadVideoExport(sessionId: string, exportId: string): Promise<ArrayBuffer>;
+  timeline(viewerUrl: string, options?: { startSeconds?: number; endSeconds?: number; paddingSeconds?: number }): Promise<Record<string, unknown>>;
+  listRuns(): Promise<Record<string, unknown>>;
+  operationsSnapshot(): Promise<OperationsSnapshot>;
+  operationsOverview(): Promise<Record<string, unknown>>;
+  getRun(runId: string): Promise<Record<string, unknown>>;
+  getTenantConfig(): Promise<Record<string, unknown>>;
+  updateTenantConfig(patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  rotateProtocolToken(): Promise<Record<string, unknown>>;
+  validateRulePack(pack: Record<string, unknown>): Promise<Record<string, unknown>>;
+  dryRunRulePack(pack: Record<string, unknown>, events: Record<string, unknown>[]): Promise<Record<string, unknown>>;
+  publishRulePack(name: string, version: string, pack: Record<string, unknown>): Promise<Record<string, unknown>>;
+  validateSourceContract(contract: Record<string, unknown>): Promise<Record<string, unknown>>;
+  dryRunSourceContract(contract: Record<string, unknown>, events: Record<string, unknown>[]): Promise<Record<string, unknown>>;
+  getAudit(options?: { cursor?: string; limit?: number }): Promise<Record<string, unknown>>;
+  semanticQuery(question: string, options?: { planner?: { plan(question: string): Promise<SemanticQueryPlan> | SemanticQueryPlan } }): Promise<Record<string, unknown>>;
+}
+
+export interface AdminClientOptions { baseUrl: string; adminToken: string; timeoutMs?: number }
+export class AdminClient {
+  constructor(options: AdminClientOptions);
+  request(method: string, path: string, body?: unknown): Promise<Record<string, unknown>>;
+  createTenant(input: { name: string; description?: string }): Promise<Record<string, unknown>>;
+  listPipelines(options?: { cursor?: string; limit?: number }): Promise<Record<string, unknown>>;
+  getPipeline(tenantId: string, pipelineId: string): Promise<Record<string, unknown>>;
+  createPipeline(tenantId: string, pipelineId: string, config: Record<string, unknown>): Promise<Record<string, unknown>>;
+  replacePipeline(tenantId: string, pipelineId: string, config: Record<string, unknown>): Promise<Record<string, unknown>>;
+  updatePipeline(tenantId: string, pipelineId: string, patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  deletePipeline(tenantId: string, pipelineId: string): Promise<Record<string, unknown>>;
+  validateRulePack(pack: Record<string, unknown>): Promise<Record<string, unknown>>;
+  dryRunRulePack(pack: Record<string, unknown>, events: Record<string, unknown>[]): Promise<Record<string, unknown>>;
+  publishRulePack(owner: string, name: string, version: string, pack: Record<string, unknown>): Promise<Record<string, unknown>>;
+  publishModelProfile(name: string, version: string, profile: Record<string, unknown>): Promise<Record<string, unknown>>;
+  getModelProfile(name: string, version: string): Promise<Record<string, unknown>>;
+  stats(): Promise<Record<string, unknown>>;
+  reindexArtifact(tenantId: string, pipelineId: string, sessionId: string): Promise<Record<string, unknown>>;
+  reliabilitySummary(): Promise<Record<string, unknown>>;
+  reliabilityList(kind: "receipts" | "outbox" | "quarantine" | "artifacts", options?: { cursor?: string; limit?: number }): Promise<Record<string, unknown>>;
+  replay(input: Record<string, unknown>): Promise<Record<string, unknown>>;
+  reconcile(input?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}

package/src/index.js

@@ -0,0 +1,607 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { DeterministicSemanticPlanner, normalizeSemanticQuery } from "./semantic-query.js";
+
+export { DeterministicSemanticPlanner, ModelSemanticPlanner, normalizeSemanticQuery } from "./semantic-query.js";
+
+const sensitiveKey = /(^|[._-])(authorization|cookie|password|passwd|secret|token|api[._-]?key|private[._-]?key)([._-]|$)/i;
+
+export function stableEventId(...parts) {
+  const canonical = JSON.stringify(sortValue(parts));
+  return `evt_${createHash("sha256").update(canonical).digest("hex")}`;
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortValue(value[key])]));
+  }
+  return value;
+}
+
+export class Privacy {
+  constructor({ captureContent = false, redactedKeys = [], maxStringLength = 4096, replacement = "[REDACTED]" } = {}) {
+    this.captureContent = captureContent;
+    this.redactedKeys = new Set(redactedKeys);
+    this.maxStringLength = maxStringLength;
+    this.replacement = replacement;
+  }
+
+  sanitize(value, { content = false } = {}) {
+    if (content && !this.captureContent) return this.replacement;
+    return this.#walk(value);
+  }
+
+  #walk(value, key = "") {
+    if (this.redactedKeys.has(key) || sensitiveKey.test(key)) return this.replacement;
+    if (Array.isArray(value)) return value.map((item) => this.#walk(item, key));
+    if (value && typeof value === "object") {
+      return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [childKey, this.#walk(child, childKey)]));
+    }
+    if (typeof value === "string" && value.length > this.maxStringLength) {
+      return `${value.slice(0, this.maxStringLength)}…[TRUNCATED]`;
+    }
+    return value;
+  }
+}
+
+function anyValue(value) {
+  if (value == null) return { stringValue: "" };
+  if (typeof value === "boolean") return { boolValue: value };
+  if (typeof value === "bigint" || Number.isInteger(value)) return { intValue: String(value) };
+  if (typeof value === "number") return { doubleValue: value };
+  if (typeof value === "object") return { stringValue: JSON.stringify(sortValue(value)) };
+  return { stringValue: String(value) };
+}
+
+function attributes(values) {
+  return Object.entries(values)
+    .filter(([, value]) => value != null)
+    .map(([key, value]) => ({ key, value: anyValue(value) }));
+}
+
+function decodeJwt(token) {
+  if (!token) return null;
+  const parts = String(token).split(".");
+  if (parts.length !== 3) throw new TypeError("tenantJwt must be a three-segment JWT");
+  try {
+    const claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    if (!claims.tenant_id || !claims.pipeline_id) throw new Error("scope missing");
+    if (claims.exp && Number(claims.exp) <= Math.floor(Date.now() / 1000)) throw new Error("expired");
+    return claims;
+  } catch (error) {
+    throw new TypeError(`tenantJwt claims are invalid: ${error.message}`);
+  }
+}
+
+function eventTimestamp(row) {
+  return row?.event?.timestamps?.observed || row?.event?.timestamps?.received || row?.event?.received_at || row?.metadata?.received_at || null;
+}
+
+function sanitizeEvent(row) {
+  const event = row?.event || {};
+  return {
+    event_id: row?.metadata?.event_id || event.event_id || null,
+    timestamp: eventTimestamp(row),
+    source_type: event.source_type || event.source?.type || "unknown",
+    event_type: event.event_type || null,
+    severity: row?.rule_evaluation?.severity || event.severity || "info",
+    message: String(event.message || event.content?.normalized?.message || "").slice(0, 2_000),
+    device_id: event.device_id || null,
+    run_id: event.run_id || event.goal_id || event.mission_id || event.recording_id || null,
+    rule_evaluation: row?.rule_evaluation || null,
+    ai_enrichment: row?.ai_enrichment || null,
+  };
+}
+
+function filterEventRows(rows, plan) {
+  const filters = plan.filters;
+  const words = [...new Set([...(filters.keywords || []), ...(plan.question.toLowerCase().match(/[a-z0-9_.:-]{2,}/gu) || [])])];
+  return rows.map((row) => {
+    const event = sanitizeEvent(row);
+    const haystack = JSON.stringify(event).toLowerCase();
+    const matched = words.filter((word) => haystack.includes(word.toLowerCase()));
+    return { event, score: words.length ? matched.length / words.length : 1, matched_terms: matched };
+  }).filter(({ event, score }) => {
+    if (filters.source_types.length && !filters.source_types.some((source) => source.endsWith(".*") ? event.source_type.startsWith(source.slice(0, -1)) : event.source_type === source)) return false;
+    if (filters.event_types.length && !filters.event_types.includes(event.event_type)) return false;
+    if (filters.severities.length && !filters.severities.includes(event.severity)) return false;
+    if (filters.device_id && event.device_id !== filters.device_id) return false;
+    if (filters.run_id && event.run_id !== filters.run_id) return false;
+    const time = Date.parse(event.timestamp || "");
+    if (filters.from && Number.isFinite(time) && time < Date.parse(filters.from)) return false;
+    if (filters.to && Number.isFinite(time) && time > Date.parse(filters.to)) return false;
+    return score > 0 || words.length === 0;
+  }).sort((a, b) => b.score - a.score).slice(0, plan.options.limit);
+}
+
+export class Span {
+  constructor(client, name, { traceId, parentSpanId, attributes: values = {} } = {}) {
+    this.client = client;
+    this.name = name;
+    this.traceId = traceId ?? randomBytes(16).toString("hex");
+    this.spanId = randomBytes(8).toString("hex");
+    this.parentSpanId = parentSpanId;
+    this.attributes = client.privacy.sanitize(values);
+    this.events = [];
+    this.startNs = BigInt(Date.now()) * 1_000_000n;
+    this.endNs = undefined;
+    this.status = { code: 0, message: "" };
+    this.ended = false;
+  }
+
+  setAttribute(key, value, { content = false } = {}) {
+    this.attributes[key] = this.client.privacy.sanitize(value, { content });
+    return this;
+  }
+
+  addEvent(name, values = {}) {
+    this.events.push({
+      timeUnixNano: String(BigInt(Date.now()) * 1_000_000n),
+      name,
+      attributes: attributes(this.client.privacy.sanitize(values)),
+    });
+    return this;
+  }
+
+  end({ error } = {}) {
+    if (this.ended) return;
+    if (error) {
+      this.status = { code: 2, message: String(error) };
+      this.addEvent("exception", { "exception.message": String(error) });
+    }
+    this.endNs = BigInt(Date.now()) * 1_000_000n;
+    this.ended = true;
+    this.client._finishSpan(this);
+  }
+
+  toOtlp() {
+    const span = {
+      traceId: this.traceId,
+      spanId: this.spanId,
+      name: this.name,
+      kind: 1,
+      startTimeUnixNano: String(this.startNs),
+      endTimeUnixNano: String(this.endNs ?? BigInt(Date.now()) * 1_000_000n),
+      attributes: attributes(this.attributes),
+      events: this.events,
+      status: this.status,
+    };
+    if (this.parentSpanId) span.parentSpanId = this.parentSpanId;
+    return span;
+  }
+}
+
+export class Run {
+  constructor(client, root, goalId) {
+    this.client = client;
+    this.root = root;
+    this.goalId = goalId;
+  }
+
+  get traceId() { return this.root.traceId; }
+  get runId() { return this.root.attributes["run.id"]; }
+
+  startSpan(name, { kind = "CHAIN", attributes: values = {} } = {}) {
+    return this.client.startSpan(name, {
+      traceId: this.traceId,
+      parentSpanId: this.root.spanId,
+      attributes: {
+        "openinference.span.kind": kind.toUpperCase(),
+        "run.id": this.runId,
+        "goal.id": this.goalId,
+        ...values,
+      },
+    });
+  }
+
+  async withSpan(name, options, operation) {
+    const span = this.startSpan(name, options);
+    try {
+      return await operation(span);
+    } catch (error) {
+      span.end({ error });
+      throw error;
+    } finally {
+      span.end();
+    }
+  }
+
+  evaluate(name, { score, label, explanation = "" }) {
+    this.root.addEvent("gen_ai.evaluation", {
+      "gen_ai.evaluation.name": name,
+      "gen_ai.evaluation.score.value": score,
+      "gen_ai.evaluation.score.label": label,
+      "gen_ai.evaluation.explanation": explanation,
+    });
+  }
+
+  end(options) { this.root.end(options); }
+}
+
+export class Client {
+  constructor({
+    baseUrl,
+    tenantId,
+    pipelineId,
+    protocolToken,
+    tenantJwt,
+    serviceName = "application",
+    serviceVersion,
+    environment,
+    privacy = new Privacy(),
+    timeoutMs = 30_000,
+    spoolDirectory,
+    maxSpoolFiles = 256,
+    autoFlushSpans = 64,
+    semanticPlanner = new DeterministicSemanticPlanner(),
+  }) {
+    if (!baseUrl) throw new TypeError("baseUrl is required");
+    const parsedBase = new URL(baseUrl);
+    if (parsedBase.protocol !== "https:") throw new TypeError("baseUrl must use HTTPS");
+    const claims = decodeJwt(tenantJwt);
+    if (claims && tenantId && tenantId !== claims.tenant_id) throw new TypeError("tenantId does not match tenantJwt scope");
+    if (claims && pipelineId && pipelineId !== claims.pipeline_id) throw new TypeError("pipelineId does not match tenantJwt scope");
+    this.baseUrl = parsedBase.origin;
+    this.tenantId = tenantId || claims?.tenant_id;
+    this.pipelineId = pipelineId || claims?.pipeline_id;
+    if (!this.tenantId || !this.pipelineId) throw new TypeError("tenantId and pipelineId are required when tenantJwt cannot supply scope");
+    this.claims = claims;
+    this.protocolToken = protocolToken;
+    this.tenantJwt = tenantJwt;
+    this.serviceName = serviceName;
+    this.serviceVersion = serviceVersion;
+    this.environment = environment;
+    this.privacy = privacy;
+    this.timeoutMs = timeoutMs;
+    this.spoolDirectory = spoolDirectory;
+    this.maxSpoolFiles = maxSpoolFiles;
+    this.autoFlushSpans = autoFlushSpans;
+    this.semanticPlanner = semanticPlanner;
+    this.pending = [];
+  }
+
+  scope() {
+    return {
+      tenant_id: this.tenantId,
+      pipeline_id: this.pipelineId,
+      subject: this.claims?.sub || null,
+      cluster_id: this.claims?.cluster_id || null,
+      app_id: this.claims?.app_id || null,
+    };
+  }
+
+  startRun(name, { runId = randomBytes(16).toString("hex"), goalId, agentId, attributes: values = {} } = {}) {
+    const root = this.startSpan(name, { attributes: {
+      "openinference.span.kind": "AGENT",
+      "gen_ai.operation.name": "invoke_agent",
+      "gen_ai.agent.id": agentId,
+      "gen_ai.agent.name": name,
+      "run.id": runId,
+      "goal.id": goalId,
+      ...values,
+    }});
+    return new Run(this, root, goalId);
+  }
+
+  startSpan(name, options) { return new Span(this, name, options); }
+
+  _finishSpan(span) {
+    this.pending.push(span);
+    if (this.pending.length >= this.autoFlushSpans) void this.flush();
+  }
+
+  _otlpPayload(spans) {
+    return { resourceSpans: [{
+      resource: { attributes: attributes({
+        "service.name": this.serviceName,
+        "service.version": this.serviceVersion,
+        "deployment.environment.name": this.environment,
+      })},
+      scopeSpans: [{
+        scope: { name: "trazio-telemetry", version: "0.3.0" },
+        spans: spans.map((span) => span.toOtlp()),
+      }],
+    }]};
+  }
+
+  async flush() {
+    await this.#drainSpool();
+    if (!this.pending.length) return;
+    const spans = this.pending.splice(0);
+    const payload = this._otlpPayload(spans);
+    try {
+      await this.#request("POST", "/v1/traces", payload, { protocol: true });
+    } catch (error) {
+      await this.#spool(payload);
+      throw error;
+    }
+  }
+
+  async recordEvent(event, { idempotencyKey } = {}) {
+    const key = idempotencyKey ?? stableEventId(this.tenantId, this.pipelineId, event);
+    const path = `/v1/ingest/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}`;
+    return this.#request("POST", path, this.privacy.sanitize(event), { jwt: true, headers: { "Idempotency-Key": key } });
+  }
+
+  async uploadArtifact(path, { format = "auto", deviceId, goalId, metadata = {} } = {}) {
+    const base = `/v1/artifacts/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}/sessions`;
+    const session = await this.#request("POST", base, {
+      filename: basename(path), format, device_id: deviceId, goal_id: goalId,
+      metadata: this.privacy.sanitize(metadata),
+    }, { jwt: true });
+    const content = await readFile(path);
+    await this.#request("PUT", `${base}/${encodeURIComponent(session.session_id)}/content`, content, {
+      jwt: true, contentType: "application/octet-stream",
+    });
+    return this.#request("POST", `${base}/${encodeURIComponent(session.session_id)}/complete`, undefined, { jwt: true });
+  }
+
+  listNoticeDeliveries({transport="room",limit=50,cursor}={}) {
+    if(!["room","moq"].includes(transport))throw new TypeError("transport must be room or moq");
+    const params=new URLSearchParams({limit:String(limit)});if(cursor)params.set("cursor",cursor);
+    return this.#request("GET",`/v1/${transport==="room"?"livekit":"live"}/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}/notice-deliveries?${params}`,undefined,{jwt:true});
+  }
+  replayNoticeDelivery(input,{transport="room"}={}) {
+    if(!["room","moq"].includes(transport))throw new TypeError("transport must be room or moq");
+    return this.#request("POST",`/v1/${transport==="room"?"livekit":"live"}/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}/notice-replay`,input,{jwt:true});
+  }
+
+  async analyzeLiveFrame(path, {
+    streamSessionId, frameId, observedAt = new Date().toISOString(),
+    deviceId, runId, goalId, contentType = "image/jpeg",
+  } = {}) {
+    if (!streamSessionId || !frameId) throw new TypeError("streamSessionId and frameId are required");
+    const content = await readFile(path);
+    const livePath = `/v1/live/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}/analyze-frame`;
+    return this.#request("POST", livePath, content, {
+      jwt: true,
+      contentType,
+      headers: {
+        "X-Stream-Session-Id": String(streamSessionId),
+        "X-Frame-Id": String(frameId),
+        "X-Observed-At": String(observedAt),
+        ...(deviceId ? { "X-Device-Id": String(deviceId) } : {}),
+        ...(runId ? { "X-Run-Id": String(runId) } : {}),
+        ...(goalId ? { "X-Goal-Id": String(goalId) } : {}),
+      },
+    });
+  }
+
+  #queryPath(suffix = "") {
+    return `/v1/query/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}${suffix}`;
+  }
+
+  #artifactPath(suffix = "") {
+    return `/v1/artifacts/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}${suffix}`;
+  }
+
+  #tenantPath(suffix = "") {
+    return `/v1/tenant/pipelines/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}${suffix}`;
+  }
+
+  async listEvents({ limit = 100, cursor, includeAi = true } = {}) {
+    const params = new URLSearchParams({ limit: String(Math.min(Math.max(Number(limit) || 100, 1), 100)), include_ai: String(Boolean(includeAi)) });
+    if (cursor) params.set("cursor", cursor);
+    return this.#request("GET", `${this.#queryPath()}?${params}`, undefined, { jwt: true });
+  }
+
+  async searchEvents(query) {
+    const plan = normalizeSemanticQuery(typeof query === "string" ? query : { ...query, targets: ["events"] });
+    const rows = [];
+    let cursor;
+    while (rows.length < plan.options.max_scan) {
+      const page = await this.listEvents({ limit: Math.min(100, plan.options.max_scan - rows.length), cursor, includeAi: true });
+      rows.push(...(page.results || []));
+      cursor = page.cursor;
+      if (!cursor || page.list_complete) break;
+    }
+    const matches = filterEventRows(rows, plan);
+    return { scope: this.scope(), plan, scanned: rows.length, count: matches.length, matches, retrieval: "structured_lexical" };
+  }
+
+  async searchArtifacts(query) {
+    const plan = normalizeSemanticQuery(typeof query === "string" ? { question: query, targets: ["artifacts"] } : { ...query, targets: ["artifacts"] });
+    const filters = plan.filters;
+    return this.#request("POST", this.#artifactPath("/search"), {
+      query: plan.question,
+      top_k: plan.options.top_k,
+      ...(filters.session_id ? { session_id: filters.session_id } : {}),
+      ...(filters.device_id ? { device_id: filters.device_id } : {}),
+      ...(filters.run_id ? { run_id: filters.run_id } : {}),
+    }, { jwt: true });
+  }
+
+  correlationGraph(options = {}) {
+    const params = new URLSearchParams();
+    for (const key of ["query", "node_id", "event_id", "edge_id", "relationship", "rule_id"])
+      if (options[key]) params.set(key, String(options[key]));
+    if (options.event_ids?.length) params.set("event_ids", options.event_ids.slice(0, 50).join(","));
+    params.set("hops", String(Math.min(Math.max(Number(options.hops) || 1, 0), 3)));
+    params.set("limit", String(Math.min(Math.max(Number(options.limit) || 100, 1), 500)));
+    return this.#request("GET", `${this.#queryPath("/graph")}?${params}`, undefined, { jwt: true });
+  }
+
+  getArtifactSession(sessionId) {
+    return this.#request("GET", this.#artifactPath(`/sessions/${encodeURIComponent(sessionId)}`), undefined, { jwt: true });
+  }
+
+  getTelemetry(sessionId) {
+    return this.#request("GET", this.#artifactPath(`/sessions/${encodeURIComponent(sessionId)}/telemetry`), undefined, { jwt: true, responseType: "text" });
+  }
+
+  downloadArtifact(sessionId) {
+    return this.#request("GET", this.#artifactPath(`/sessions/${encodeURIComponent(sessionId)}/content`), undefined, { jwt: true, responseType: "buffer" });
+  }
+
+  async openVideo(sessionId, { title, ttlSeconds = 900, embedOrigin } = {}) {
+    const result = await this.#request("POST", this.#artifactPath(`/sessions/${encodeURIComponent(sessionId)}/playback`), {
+      title, ttl_seconds: Math.min(Math.max(Number(ttlSeconds) || 900, 60), 3600),
+      ...(embedOrigin?{embed_origin:embedOrigin}:{}),
+    }, { jwt: true });
+    return { ...result, viewer_url: new URL(result.viewer_url, this.baseUrl).toString() };
+  }
+
+  renewPlayback(sessionId, token) { return this.#request("POST", this.#artifactPath(`/sessions/${encodeURIComponent(sessionId)}/playback-renew`), {token}, {jwt:true}); }
+  createLiveEmbed(options) { return this.#request("POST", `/v1/live/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}/viewer-grants`, options, {jwt:true}); }
+  renewLiveEmbed(grantId) { return this.#request("PATCH", `/v1/live/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}/viewer-grants/${encodeURIComponent(grantId)}`, undefined, {jwt:true}); }
+  revokeLiveEmbed(grantId) { return this.#request("DELETE", `/v1/live/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}/viewer-grants/${encodeURIComponent(grantId)}`, undefined, {jwt:true}); }
+  revokePlayback(sessionId, token) { return this.#request("POST", this.#artifactPath(`/sessions/${encodeURIComponent(sessionId)}/playback-revoke`), {token}, {jwt:true}); }
+  requestVideoExport(sessionId, {startSeconds,endSeconds,idempotencyKey}) {
+    return this.#request("POST",this.#artifactPath(`/sessions/${encodeURIComponent(sessionId)}/exports`),{start_seconds:startSeconds,end_seconds:endSeconds},{jwt:true,headers:{"Idempotency-Key":idempotencyKey}});
+  }
+  getVideoExport(sessionId, exportId) { return this.#request("GET",this.#artifactPath(`/sessions/${encodeURIComponent(sessionId)}/exports/${encodeURIComponent(exportId)}`),undefined,{jwt:true}); }
+  downloadVideoExport(sessionId, exportId) { return this.#request("GET",this.#artifactPath(`/sessions/${encodeURIComponent(sessionId)}/exports/${encodeURIComponent(exportId)}/content`),undefined,{jwt:true,responseType:"buffer"}); }
+
+  timeline(viewerUrl, { startSeconds = 0, endSeconds = startSeconds, paddingSeconds = 5 } = {}) {
+    const url = new URL(viewerUrl, this.baseUrl);
+    if (url.origin !== this.baseUrl || !/^\/v1\/artifacts\/play\/(?:pc_[a-f0-9]{32}\/)?pb_[A-Za-z0-9_-]+$/u.test(url.pathname)) throw new TypeError("viewerUrl must be an opaque URL issued by this regional service");
+    const params = new URLSearchParams({ start: String(startSeconds), end: String(endSeconds), padding: String(Math.min(Math.max(Number(paddingSeconds) || 0, 0), 60)) });
+    return this.#request("GET", `${url.pathname}/timeline?${params}`, undefined, { publicRequest: true });
+  }
+
+  listRuns() { return this.#request("GET", this.#artifactPath("/runs"), undefined, { jwt: true }); }
+  operationsSnapshot() {
+    return this.#request("GET", `/v1/operations/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}/snapshot`, undefined, { jwt: true });
+  }
+  operationsOverview() {
+    return this.#request("GET", `/v1/operations/${encodeURIComponent(this.tenantId)}/${encodeURIComponent(this.pipelineId)}/overview`, undefined, { jwt: true });
+  }
+  getRun(runId) { return this.#request("GET", this.#artifactPath(`/runs/${encodeURIComponent(runId)}`), undefined, { jwt: true }); }
+  getTenantConfig() { return this.#request("GET", this.#tenantPath("/config"), undefined, { jwt: true }); }
+  updateTenantConfig(patch) { return this.#request("PATCH", this.#tenantPath("/config"), patch, { jwt: true }); }
+  rotateProtocolToken() { return this.#request("POST", this.#tenantPath("/protocol-token/rotate"), {}, { jwt: true }); }
+  validateRulePack(pack) { return this.#request("POST", this.#tenantPath("/rule-packs/validate"), pack, { jwt: true }); }
+  dryRunRulePack(pack, events) { return this.#request("POST", this.#tenantPath("/rule-packs/dry-run"), { pack, events }, { jwt: true }); }
+  publishRulePack(name, version, pack) { return this.#request("POST", this.#tenantPath(`/rule-packs/${encodeURIComponent(name)}/${encodeURIComponent(version)}`), pack, { jwt: true }); }
+  validateSourceContract(contract) { return this.#request("POST", this.#tenantPath("/contracts/validate"), contract, { jwt: true }); }
+  dryRunSourceContract(contract, events) { return this.#request("POST", this.#tenantPath("/contracts/dry-run"), { contract, events }, { jwt: true }); }
+  getAudit({ cursor, limit = 100 } = {}) {
+    const params = new URLSearchParams({ limit: String(Math.min(Math.max(Number(limit) || 100, 1), 100)) });
+    if (cursor) params.set("cursor", cursor);
+    return this.#request("GET", `${this.#tenantPath("/audit")}?${params}`, undefined, { jwt: true });
+  }
+
+  async semanticQuery(question, { planner = this.semanticPlanner } = {}) {
+    const plan = normalizeSemanticQuery(await planner.plan(question), { question });
+    const result = { scope: this.scope(), plan, events: null, artifacts: null, graph: null, errors: {} };
+    const operations = {
+      events: () => this.searchEvents(plan),
+      artifacts: () => this.searchArtifacts(plan),
+      graph: () => this.correlationGraph({
+        query: plan.question, relationship: plan.filters.relationship, rule_id: plan.filters.rule_id,
+        hops: plan.options.graph_hops, limit: Math.min(plan.options.limit * 5, 500),
+      }),
+    };
+    await Promise.all(plan.targets.map(async (target) => {
+      try { result[target] = await operations[target](); }
+      catch (error) { result.errors[target] = { name: error?.name || "Error", message: String(error?.message || "query failed").slice(0, 500) }; }
+    }));
+    return { ...result, reliability: { scope_source: "jwt_claims_server_verified_per_request", plan_validated: true, raw_records_merged: false } };
+  }
+
+  #auth({ protocol, jwt }) {
+    const token = protocol ? this.protocolToken : jwt ? this.tenantJwt : undefined;
+    if (!token) throw new TypeError(`${protocol ? "protocolToken" : "tenantJwt"} is required for this operation`);
+    const headers = { Authorization: `Bearer ${token}` };
+    if (protocol) {
+      headers["X-Platform-Tenant"] = this.tenantId;
+      headers["X-Platform-Pipeline"] = this.pipelineId;
+    }
+    return headers;
+  }
+
+  async #request(method, path, payload, { protocol = false, jwt = false, publicRequest = false, headers = {}, contentType = "application/json", responseType = "json" } = {}) {
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      redirect: "error",
+      signal: AbortSignal.timeout(this.timeoutMs),
+      headers: { ...(publicRequest ? {} : this.#auth({ protocol, jwt })), "Content-Type": contentType, ...headers },
+      body: payload == null ? undefined : Buffer.isBuffer(payload) ? payload : JSON.stringify(payload),
+    });
+    if (responseType === "buffer") {
+      const buffer = Buffer.from(await response.arrayBuffer());
+      if (!response.ok) throw new Error(`HTTP ${response.status} from ${path}`);
+      return buffer;
+    }
+    const text = await response.text();
+    if (!response.ok) throw new Error(`HTTP ${response.status} from ${path}: ${text.slice(0, 2048)}`);
+    if (responseType === "text") return text;
+    return text ? JSON.parse(text) : { status: response.status };
+  }
+
+  async #spool(payload) {
+    if (!this.spoolDirectory) return;
+    await mkdir(this.spoolDirectory, { recursive: true, mode: 0o700 });
+    const files = (await readdir(this.spoolDirectory)).filter((name) => name.endsWith(".json")).sort();
+    while (files.length >= this.maxSpoolFiles) await unlink(join(this.spoolDirectory, files.shift()));
+    await writeFile(join(this.spoolDirectory, `${Date.now()}-${randomBytes(4).toString("hex")}.json`), JSON.stringify(payload), { mode: 0o600 });
+  }
+
+  async #drainSpool() {
+    if (!this.spoolDirectory) return;
+    await mkdir(this.spoolDirectory, { recursive: true, mode: 0o700 });
+    const files = (await readdir(this.spoolDirectory)).filter((name) => name.endsWith(".json")).sort();
+    for (const name of files) {
+      const payload = JSON.parse(await readFile(join(this.spoolDirectory, name), "utf8"));
+      await this.#request("POST", "/v1/traces", payload, { protocol: true });
+      await unlink(join(this.spoolDirectory, name));
+    }
+  }
+}
+
+export class AdminClient {
+  constructor({ baseUrl, adminToken, timeoutMs = 30_000 }) {
+    const url = new URL(baseUrl);
+    if (url.protocol !== "https:") throw new TypeError("baseUrl must use HTTPS");
+    if (!adminToken) throw new TypeError("adminToken is required");
+    this.baseUrl = url.origin;
+    this.adminToken = adminToken;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async request(method, path, body) {
+    if (!String(path).startsWith("/v1/admin/")) throw new TypeError("Admin requests must use /v1/admin paths");
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      signal: AbortSignal.timeout(this.timeoutMs),
+      headers: { "X-Admin-Token": this.adminToken, Accept: "application/json", ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const text = await response.text();
+    let payload;
+    try { payload = text ? JSON.parse(text) : { status: response.status }; } catch { payload = { error: text.slice(0, 2_000) }; }
+    if (!response.ok) throw new Error(`HTTP ${response.status} from ${path}: ${String(payload?.error || "admin request failed").slice(0, 500)}`);
+    return payload;
+  }
+
+  createTenant(input) { return this.request("POST", "/v1/admin/customers", input); }
+  listPipelines({ cursor, limit = 100 } = {}) {
+    const params = new URLSearchParams({ limit: String(Math.min(Math.max(Number(limit) || 100, 1), 100)) });
+    if (cursor) params.set("cursor", cursor);
+    return this.request("GET", `/v1/admin/pipelines?${params}`);
+  }
+  pipelinePath(tenantId, pipelineId, suffix = "") { return `/v1/admin/pipelines/${encodeURIComponent(tenantId)}/${encodeURIComponent(pipelineId)}${suffix}`; }
+  getPipeline(tenantId, pipelineId) { return this.request("GET", this.pipelinePath(tenantId, pipelineId)); }
+  createPipeline(tenantId, pipelineId, config) { return this.request("POST", this.pipelinePath(tenantId, pipelineId), config); }
+  replacePipeline(tenantId, pipelineId, config) { return this.request("PUT", this.pipelinePath(tenantId, pipelineId), config); }
+  updatePipeline(tenantId, pipelineId, patch) { return this.request("PATCH", this.pipelinePath(tenantId, pipelineId), patch); }
+  deletePipeline(tenantId, pipelineId) { return this.request("DELETE", this.pipelinePath(tenantId, pipelineId)); }
+  validateRulePack(pack) { return this.request("POST", "/v1/admin/rule-packs/validate", pack); }
+  dryRunRulePack(pack, events) { return this.request("POST", "/v1/admin/rule-packs/dry-run", { pack, events }); }
+  publishRulePack(owner, name, version, pack) { return this.request("POST", `/v1/admin/rule-packs/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/${encodeURIComponent(version)}`, pack); }
+  publishModelProfile(name, version, profile) { return this.request("POST", `/v1/admin/model-profiles/${encodeURIComponent(name)}/${encodeURIComponent(version)}`, profile); }
+  getModelProfile(name, version) { return this.request("GET", `/v1/admin/model-profiles/${encodeURIComponent(name)}/${encodeURIComponent(version)}`); }
+  stats() { return this.request("GET", "/v1/admin/stats"); }
+  reindexArtifact(tenantId, pipelineId, sessionId) { return this.request("POST", `/v1/admin/artifacts/${encodeURIComponent(tenantId)}/${encodeURIComponent(pipelineId)}/${encodeURIComponent(sessionId)}/reindex`, {}); }
+  reliabilitySummary() { return this.request("GET", "/v1/admin/reliability/summary"); }
+  reliabilityList(kind, { cursor, limit = 100 } = {}) {
+    if (!["receipts", "outbox", "quarantine", "artifacts"].includes(kind)) throw new TypeError("Unsupported reliability collection");
+    const params = new URLSearchParams({ limit: String(Math.min(Math.max(Number(limit) || 100, 1), 100)) });
+    if (cursor) params.set("cursor", cursor);
+    return this.request("GET", `/v1/admin/reliability/${kind}?${params}`);
+  }
+  replay(input) { return this.request("POST", "/v1/admin/reliability/replay", input); }
+  reconcile(input = {}) { return this.request("POST", "/v1/admin/reliability/reconcile", input); }
+}

package/src/integrations.d.ts

@@ -0,0 +1,9 @@
+export function openInferenceAttributes(kind: string, values?: Record<string, unknown> & { inputValue?: unknown; outputValue?: unknown }): Record<string, unknown>;
+export function temporalAttributes(values: {
+  workflowId: string;
+  runId: string;
+  workflowType?: string;
+  taskQueue?: string;
+  activityId?: string;
+  attempt?: number;
+}): Record<string, unknown>;

package/src/integrations.js

@@ -0,0 +1,20 @@
+export function openInferenceAttributes(kind, { inputValue, outputValue, ...attributes } = {}) {
+  return {
+    "openinference.span.kind": kind.toUpperCase(),
+    ...(inputValue === undefined ? {} : { "input.value": inputValue }),
+    ...(outputValue === undefined ? {} : { "output.value": outputValue }),
+    ...attributes,
+  };
+}
+
+export function temporalAttributes({ workflowId, runId, workflowType, taskQueue, activityId, attempt }) {
+  return {
+    "temporal.workflow.id": workflowId,
+    "temporal.run.id": runId,
+    "temporal.workflow.type": workflowType,
+    "temporal.task_queue": taskQueue,
+    "temporal.activity.id": activityId,
+    "temporal.activity.attempt": attempt,
+    "run.id": runId,
+  };
+}

package/src/semantic-query.js

@@ -0,0 +1,144 @@
+import { createHash } from "node:crypto";
+
+const SEVERITIES = new Set(["info", "low", "medium", "high", "critical"]);
+const TARGETS = new Set(["events", "artifacts", "graph"]);
+const MODES = new Set(["hybrid", "semantic", "lexical", "structured"]);
+const SOURCE_ALIASES = new Map([
+  ["kubernetes", "kubernetes.*"], ["k8s", "kubernetes.*"],
+  ["otel", "otel.*"], ["opentelemetry", "otel.*"],
+  ["robot", "robot.*"], ["robotics", "robot.*"],
+  ["desktop", "desktop.*"], ["endpoint", "desktop.security"],
+  ["argocd", "argocd"], ["mqtt", "mqtt"],
+]);
+
+function list(value, { allowed, limit = 32 } = {}) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) throw new TypeError("Semantic query list fields must be arrays");
+  const output = [...new Set(value.map((item) => String(item).trim()).filter(Boolean))].slice(0, limit);
+  if (allowed && output.some((item) => !allowed.has(item))) throw new TypeError("Semantic query contains an unsupported value");
+  return output;
+}
+
+function boundedString(value, name, maximum = 4_000) {
+  const text = String(value ?? "").trim();
+  if (!text || text.length > maximum) throw new TypeError(`${name} must contain 1-${maximum} characters`);
+  return text;
+}
+
+function timestamp(value, name) {
+  if (value == null || value === "") return null;
+  const parsed = new Date(value);
+  if (!Number.isFinite(parsed.getTime())) throw new TypeError(`${name} must be an ISO-8601 timestamp`);
+  return parsed.toISOString();
+}
+
+function defaultPlan(question, now = new Date()) {
+  const lower = question.toLowerCase();
+  const severities = [...SEVERITIES].filter((severity) => new RegExp(`\\b${severity}\\b`, "u").test(lower));
+  const sourceTypes = [];
+  for (const [alias, source] of SOURCE_ALIASES) {
+    if (new RegExp(`\\b${alias}\\b`, "u").test(lower)) sourceTypes.push(source);
+  }
+  const targets = ["events"];
+  if (/\b(video|scene|recording|mcap|image|artifact|file)\b/u.test(lower)) targets.push("artifacts");
+  if (/\b(correlat|relationship|related|graph|trace|neighbor)\w*\b/u.test(lower)) targets.push("graph");
+  let from = null;
+  const recent = lower.match(/\b(?:last|past)\s+(\d{1,4})\s*(minute|hour|day|week)s?\b/u);
+  if (recent) {
+    const multipliers = { minute: 60_000, hour: 3_600_000, day: 86_400_000, week: 604_800_000 };
+    from = new Date(now.getTime() - Number(recent[1]) * multipliers[recent[2]]).toISOString();
+  }
+  return {
+    version: "1.0",
+    question,
+    mode: "hybrid",
+    targets: [...new Set(targets)],
+    filters: { source_types: [...new Set(sourceTypes)], event_types: [], severities, from, to: null },
+    options: { limit: 20, max_scan: 300, top_k: 10, graph_hops: 1 },
+    planner: { kind: "deterministic", model: null },
+  };
+}
+
+export function normalizeSemanticQuery(input, { question, planner = {} } = {}) {
+  const raw = typeof input === "string" ? defaultPlan(boundedString(input, "question")) : input;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new TypeError("Semantic query must be an object");
+  for (const forbidden of ["tenant_id", "pipeline_id", "base_url", "authorization", "token"])
+    if (Object.hasOwn(raw, forbidden)) throw new TypeError(`Semantic query cannot set ${forbidden}`);
+  const actualQuestion = boundedString(question ?? raw.question, "question");
+  const filters = raw.filters && typeof raw.filters === "object" ? raw.filters : {};
+  const options = raw.options && typeof raw.options === "object" ? raw.options : {};
+  const mode = String(raw.mode || "hybrid");
+  if (!MODES.has(mode)) throw new TypeError("Unsupported semantic query mode");
+  const targets = list(raw.targets?.length ? raw.targets : ["events"], { allowed: TARGETS, limit: 3 });
+  const from = timestamp(filters.from, "filters.from");
+  const to = timestamp(filters.to, "filters.to");
+  if (from && to && Date.parse(from) > Date.parse(to)) throw new TypeError("filters.from must not be after filters.to");
+  const normalized = {
+    version: "1.0",
+    question: actualQuestion,
+    mode,
+    targets,
+    filters: {
+      source_types: list(filters.source_types, { limit: 20 }),
+      event_types: list(filters.event_types, { limit: 20 }),
+      severities: list(filters.severities, { allowed: SEVERITIES, limit: 5 }),
+      keywords: list(filters.keywords, { limit: 32 }),
+      device_id: filters.device_id ? boundedString(filters.device_id, "filters.device_id", 200) : null,
+      run_id: filters.run_id ? boundedString(filters.run_id, "filters.run_id", 300) : null,
+      session_id: filters.session_id ? boundedString(filters.session_id, "filters.session_id", 200) : null,
+      relationship: filters.relationship ? boundedString(filters.relationship, "filters.relationship", 100) : null,
+      rule_id: filters.rule_id ? boundedString(filters.rule_id, "filters.rule_id", 200) : null,
+      from,
+      to,
+    },
+    options: {
+      limit: Math.min(Math.max(Number(options.limit) || 20, 1), 100),
+      max_scan: Math.min(Math.max(Number(options.max_scan) || 300, 1), 500),
+      top_k: Math.min(Math.max(Number(options.top_k) || 10, 1), 50),
+      graph_hops: Math.min(Math.max(Number(options.graph_hops) || 1, 0), 3),
+    },
+    planner: {
+      kind: String(planner.kind || raw.planner?.kind || "deterministic"),
+      model: planner.model || raw.planner?.model || null,
+    },
+  };
+  normalized.plan_hash = createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+  return normalized;
+}
+
+export class DeterministicSemanticPlanner {
+  plan(question) { return normalizeSemanticQuery(defaultPlan(boundedString(question, "question"))); }
+}
+
+export class ModelSemanticPlanner {
+  constructor({ generateObject, model = "unspecified", fallback = new DeterministicSemanticPlanner() }) {
+    if (typeof generateObject !== "function") throw new TypeError("generateObject must be a function");
+    this.generateObject = generateObject;
+    this.model = model;
+    this.fallback = fallback;
+  }
+
+  async plan(question) {
+    const cleanQuestion = boundedString(question, "question");
+    try {
+      const candidate = await this.generateObject({
+        question: cleanQuestion,
+        contract: "semantic-query-plan/1.0",
+        allowed_targets: [...TARGETS],
+        allowed_modes: [...MODES],
+        allowed_severities: [...SEVERITIES],
+        instruction: "Return only a query plan. Never produce tenant, pipeline, URL, token, SQL, or authorization fields.",
+      });
+      return normalizeSemanticQuery(candidate, {
+        question: cleanQuestion,
+        planner: { kind: "model", model: this.model },
+      });
+    } catch (error) {
+      const plan = await this.fallback.plan(cleanQuestion);
+      return {
+        ...normalizeSemanticQuery(plan, { question: cleanQuestion, planner: { kind: "deterministic_fallback", model: this.model } }),
+        planner_error: error?.name || "invalid_model_plan",
+      };
+    }
+  }
+}