zansn 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0
+
+Initial public developer starter kit.
+
+- Added local-first evaluation runner.
+- Added Zansn evidence-pack schema `zansn.evidence-pack.v0`.
+- Added task, trace, finding, policy, usage, and readiness types.
+- Added tool allow/block policy checks.
+- Added configurable sensitive-data pattern checks.
+- Added cost and latency policy checks.
+- Added JSON and Markdown evidence-pack exporters.
+- Added evidence-pack validation.
+- Added OpenTelemetry-compatible attribute mapping.
+

package/LICENSE

@@ -0,0 +1,18 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+Copyright 2026 Zansn Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

package/README.md

@@ -0,0 +1,346 @@
+# zansn
+
+<p align="center">
+  <a href="https://zansn.ai">
+    <img src="./assets/zansn-logo.png" alt="Zansn Labs logo" width="96" height="96">
+  </a>
+</p>
+
+Local-first AI assurance primitives for evaluating agent workflows and producing portable evidence packs.
+
+Website: https://zansn.ai
+
+Zansn Labs builds AI assurance infrastructure for agentic, data-sensitive, and scientific AI workflows. `zansn` is the open-source developer entry point: it runs locally, captures agent-aware traces, checks basic policy and privacy boundaries, profiles cost and latency, and returns a structured evidence artifact that can be versioned, reviewed, or later ingested by commercial assurance infrastructure.
+
+## Why Developers Use It
+
+Agent demos are easy. Deployment evidence is hard.
+
+Use `zansn` when you need to answer:
+
+- Did the agent complete the task?
+- Which tools did it call?
+- Did it call a blocked or unexpected tool?
+- Did output cross a configured privacy boundary?
+- What did the run cost?
+- How long did it take?
+- Which findings block deployment?
+- Can this run be attached to a pull request, experiment record, or review workflow?
+
+## Install
+
+```bash
+npm install zansn
+```
+
+Requirements:
+
+- Node.js 18 or newer
+- ESM project or bundler-compatible TypeScript setup
+
+## Run the Example
+
+After installation, run the included example:
+
+```bash
+node node_modules/zansn/examples/basic-evaluation.mjs
+```
+
+The example runs a local evaluation and prints a Markdown evidence pack.
+
+## Quick Start
+
+```ts
+import {
+  ZansnClient,
+  exportEvidencePackMarkdown,
+  validateEvidencePack
+} from "zansn";
+
+const zansn = new ZansnClient({
+  defaultPolicy: {
+    allowedTools: ["lookupCustomer"],
+    blockedTools: ["deleteCustomer"],
+    sensitiveDataPatterns: [/sk-[a-z0-9]+/i],
+    maxEstimatedCostUsd: 0.05,
+    maxLatencyMs: 5_000,
+    minimumScore: 1
+  }
+});
+
+const evidence = await zansn.runEvaluation({
+  projectId: "ZAN-RD-001",
+  experimentId: "ZAN-EXP-001",
+  name: "Customer support agent readiness check",
+  tasks: [
+    {
+      id: "support-001",
+      input: "Check whether ACME has an active support plan.",
+      expected: "active"
+    }
+  ],
+  execute: async (task, context) => {
+    context.recordEvent({
+      type: "agent",
+      name: "agent.plan",
+      attributes: {
+        taskInput: task.input,
+        step: "lookup_customer_status"
+      }
+    });
+
+    return {
+      output: "active",
+      toolCalls: [
+        {
+          name: "lookupCustomer",
+          arguments: { customer: "ACME" },
+          result: { plan: "active" },
+          status: "ok"
+        }
+      ],
+      usage: {
+        inputTokens: 140,
+        outputTokens: 32,
+        estimatedCostUsd: 0.004
+      }
+    };
+  }
+});
+
+const validation = validateEvidencePack(evidence);
+if (!validation.valid) {
+  throw new Error(validation.errors.join("\n"));
+}
+
+console.log(evidence.summary);
+console.log(exportEvidencePackMarkdown(evidence));
+```
+
+## Evidence Pack
+
+`runEvaluation()` returns a portable evidence artifact:
+
+```ts
+{
+  schema: "zansn.evidence-pack.v0",
+  runId: "zan-run-...",
+  projectId: "ZAN-RD-001",
+  experimentId: "ZAN-EXP-001",
+  name: "Customer support agent readiness check",
+  summary: {
+    tasks: 1,
+    passed: 1,
+    failed: 0,
+    blocked: 0,
+    passRate: 1,
+    averageScore: 1,
+    totalEstimatedCostUsd: 0.004,
+    totalTokens: 172,
+    p50LatencyMs: 14,
+    p95LatencyMs: 14,
+    highestSeverity: "info",
+    readiness: "ready"
+  },
+  taskResults: [],
+  traces: [],
+  findings: []
+}
+```
+
+Readiness values:
+
+- `ready`: no blocking findings and score meets policy.
+- `review`: non-blocking findings or score below policy threshold.
+- `blocked`: high/critical findings, privacy boundary failures, blocked tool use, or runtime failure.
+
+## API
+
+### `ZansnClient`
+
+```ts
+import { ZansnClient } from "zansn";
+
+const client = new ZansnClient({
+  organization: "Zansn Labs",
+  defaultPolicy: {
+    allowedTools: ["search", "lookup"],
+    blockedTools: ["deleteUser"],
+    sensitiveDataPatterns: [/api_key/i],
+    maxEstimatedCostUsd: 0.10,
+    maxLatencyMs: 10_000,
+    minimumScore: 0.8
+  },
+  metadata: {
+    environment: "ci"
+  }
+});
+```
+
+### `client.runEvaluation(options)`
+
+Runs a local task set against any agent, model wrapper, workflow, or function.
+
+```ts
+const evidence = await client.runEvaluation({
+  projectId: "ZAN-RD-002",
+  tasks: [
+    {
+      id: "task-001",
+      input: "Summarise policy",
+      expected: "approved"
+    }
+  ],
+  execute: async () => ({ output: "approved" })
+});
+```
+
+`execute` can return either raw output or a structured result:
+
+```ts
+return {
+  output: "approved",
+  toolCalls: [{ name: "lookupPolicy", status: "ok" }],
+  usage: { inputTokens: 50, outputTokens: 10, estimatedCostUsd: 0.001 },
+  traces: [{ type: "model", name: "model.call" }],
+  metadata: { provider: "local" }
+};
+```
+
+### `context.recordEvent(event)`
+
+Records agent-aware trace events during execution.
+
+```ts
+context.recordEvent({
+  type: "retrieval",
+  name: "documents.search",
+  attributes: {
+    query: "deployment policy"
+  }
+});
+```
+
+### `validateEvidencePack(pack)`
+
+Checks the structural contract before storing or exporting.
+
+```ts
+const result = validateEvidencePack(evidence);
+```
+
+### `exportEvidencePackJson(pack)`
+
+Exports stable JSON with deterministic object-key ordering.
+
+```ts
+import { exportEvidencePackJson } from "zansn";
+
+const json = exportEvidencePackJson(evidence);
+```
+
+### `exportEvidencePackMarkdown(pack)`
+
+Exports a human-readable local review report.
+
+```ts
+import { exportEvidencePackMarkdown } from "zansn";
+
+const report = exportEvidencePackMarkdown(evidence);
+```
+
+### `toOpenTelemetryAttributes(event)`
+
+Maps a Zansn trace event to attributes suitable for attaching to OpenTelemetry spans.
+
+```ts
+import { toOpenTelemetryAttributes } from "zansn";
+
+const attributes = toOpenTelemetryAttributes(evidence.traces[0]);
+```
+
+### `createEvidenceRecord(input)`
+
+Creates a standalone immutable evidence record for research notes, experiment logs, or review trails.
+
+```ts
+import { createEvidenceRecord } from "zansn";
+
+const record = createEvidenceRecord({
+  projectId: "ZAN-RD-017",
+  summary: "Evidence graph schema drafted"
+});
+```
+
+## What This Package Is
+
+`zansn` is intentionally:
+
+- local-first
+- vendor-neutral
+- framework-agnostic
+- TypeScript-native
+- evidence-pack oriented
+- safe to use without a Zansn account
+- suitable for CI, prototypes, research notes, and Assurance Sprint-style workflows
+
+## What This Package Is Not
+
+This package is not the full commercial Zansn Assurance Control Plane.
+
+It does not include:
+
+- hosted evidence graph
+- team workspaces
+- SSO, RBAC, audit logs, or retention controls
+- premium attack packs
+- long-running orchestration
+- managed trace storage
+- deployment approval workflows
+- geospatial benchmark libraries
+- enterprise reporting templates
+
+Those belong in future commercial or separately packaged modules. The open-source boundary is deliberate: this package creates portable local evidence artifacts, while future Zansn products can ingest, govern, compare, visualise, and operationalise those artifacts.
+
+## Package Boundary
+
+The stable contract is the evidence pack:
+
+```ts
+schema: "zansn.evidence-pack.v0"
+```
+
+Future Zansn Cloud, private deployments, or enterprise products should build around this artifact rather than forcing developers to rewrite local evaluation code.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+npm run release:check
+```
+
+## Publish
+
+`zansn` is an unscoped public npm package. Run the release check first, then publish from an authenticated npm account:
+
+```bash
+npm run release:check
+npm publish
+```
+
+## Security
+
+`zansn` runs locally and does not transmit data to Zansn Labs.
+
+Do not put production secrets, private customer data, or sensitive traces into public examples or issue reports. See `SECURITY.md`.
+
+## Source Availability
+
+The source repository is currently private while the public SDK, examples, and package boundary mature. Public support and security contact are routed through https://zansn.ai/contact. This package is published with source maps omitted and a minimal runtime tarball.
+
+## License
+
+Apache-2.0

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported Versions
+
+`zansn` is pre-1.0 software. Security fixes will target the latest published minor version.
+
+## Reporting a Vulnerability
+
+Report security issues through https://zansn.ai/contact.
+
+Do not include secrets, private customer data, or sensitive production traces in public issues or examples.
+
+## Scope
+
+`zansn` runs locally and does not transmit data to Zansn Labs. Future hosted or enterprise products should have separate security documentation, data-retention controls, and disclosure channels.

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+declare const ZANSN_EVIDENCE_PACK_SCHEMA: "zansn.evidence-pack.v0";
+declare const ZANSN_EVIDENCE_RECORD_SCHEMA: "zansn.evidence-record.v0";
+type ZansnSeverity = "info" | "low" | "medium" | "high" | "critical";
+type ZansnFindingKind = "evaluation" | "trace" | "security" | "privacy" | "cost" | "latency" | "runtime";
+type ZansnReadiness = "ready" | "review" | "blocked";
+type ZansnTraceType = "task" | "agent" | "model" | "tool" | "retrieval" | "security" | "privacy" | "metric";
+type ZansnTask<TInput = unknown, TExpected = unknown> = {
+    id: string;
+    input: TInput;
+    expected?: TExpected;
+    metadata?: ZansnMetadata;
+};
+type ZansnAgentResult<TOutput = unknown> = {
+    output: TOutput;
+    toolCalls?: ZansnToolCall[];
+    usage?: ZansnUsage;
+    traces?: ZansnTraceInput[];
+    metadata?: ZansnMetadata;
+};
+type ZansnToolCall = {
+    id?: string;
+    name: string;
+    arguments?: unknown;
+    result?: unknown;
+    status?: "ok" | "error" | "blocked";
+    startedAt?: string;
+    endedAt?: string;
+    metadata?: ZansnMetadata;
+};
+type ZansnUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    estimatedCostUsd?: number;
+};
+type ZansnTraceInput = {
+    type: ZansnTraceType;
+    name: string;
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+    attributes?: ZansnMetadata;
+};
+type ZansnTraceEvent = {
+    id: string;
+    runId: string;
+    taskId: string;
+    type: ZansnTraceType;
+    name: string;
+    startedAt: string;
+    endedAt?: string;
+    durationMs?: number;
+    attributes: ZansnMetadata;
+};
+type ZansnFinding = {
+    id: string;
+    kind: ZansnFindingKind;
+    severity: ZansnSeverity;
+    taskId?: string;
+    title: string;
+    detail: string;
+    evidence?: ZansnMetadata;
+};
+type ZansnPolicy = {
+    allowedTools?: string[];
+    blockedTools?: string[];
+    sensitiveDataPatterns?: RegExp[];
+    maxEstimatedCostUsd?: number;
+    maxLatencyMs?: number;
+    minimumScore?: number;
+};
+type ZansnRunOptions<TInput, TOutput, TExpected> = {
+    projectId: string;
+    experimentId?: string;
+    name?: string;
+    description?: string;
+    tasks: ZansnTask<TInput, TExpected>[];
+    policy?: ZansnPolicy;
+    metadata?: ZansnMetadata;
+    execute: (task: ZansnTask<TInput, TExpected>, context: ZansnRunContext) => Promise<ZansnAgentResult<TOutput> | TOutput>;
+    score?: (args: {
+        task: ZansnTask<TInput, TExpected>;
+        result: ZansnAgentResult<TOutput>;
+    }) => Promise<number> | number;
+};
+type ZansnRunContext = {
+    runId: string;
+    taskId: string;
+    recordEvent: (event: ZansnTraceInput) => ZansnTraceEvent;
+};
+type ZansnTaskResult<TOutput = unknown> = {
+    taskId: string;
+    passed: boolean;
+    score: number;
+    readiness: ZansnReadiness;
+    output?: TOutput;
+    error?: string;
+    durationMs: number;
+    usage: Required<ZansnUsage>;
+    findings: ZansnFinding[];
+    metadata: ZansnMetadata;
+};
+type ZansnEvidenceSummary = {
+    tasks: number;
+    passed: number;
+    failed: number;
+    blocked: number;
+    passRate: number;
+    averageScore: number;
+    totalEstimatedCostUsd: number;
+    totalTokens: number;
+    p50LatencyMs: number;
+    p95LatencyMs: number;
+    highestSeverity: ZansnSeverity;
+    readiness: ZansnReadiness;
+};
+type ZansnEvidencePack<TOutput = unknown> = {
+    schema: typeof ZANSN_EVIDENCE_PACK_SCHEMA;
+    runId: string;
+    projectId: string;
+    experimentId: string;
+    name: string;
+    description?: string;
+    createdAt: string;
+    completedAt: string;
+    metadata: ZansnMetadata;
+    summary: ZansnEvidenceSummary;
+    taskResults: ZansnTaskResult<TOutput>[];
+    traces: ZansnTraceEvent[];
+    findings: ZansnFinding[];
+};
+type ZansnEvidenceRecord = {
+    schema: typeof ZANSN_EVIDENCE_RECORD_SCHEMA;
+    id: string;
+    projectId: string;
+    experimentId: string;
+    createdAt: string;
+    summary: string;
+    metadata: ZansnMetadata;
+};
+type ZansnClientOptions = {
+    organization?: string;
+    defaultPolicy?: ZansnPolicy;
+    metadata?: ZansnMetadata;
+};
+type ZansnValidationResult = {
+    valid: boolean;
+    errors: string[];
+};
+type ZansnMetadata = Record<string, unknown>;
+declare class ZansnClient {
+    readonly organization: string;
+    readonly defaultPolicy: ZansnPolicy;
+    readonly metadata: ZansnMetadata;
+    constructor(options?: ZansnClientOptions);
+    runEvaluation<TInput = unknown, TOutput = unknown, TExpected = unknown>(options: ZansnRunOptions<TInput, TOutput, TExpected>): Promise<ZansnEvidencePack<TOutput>>;
+}
+declare function createEvidenceRecord(input: {
+    projectId: string;
+    experimentId?: string;
+    summary: string;
+    metadata?: ZansnMetadata;
+}): ZansnEvidenceRecord;
+declare function validateEvidencePack(value: unknown): ZansnValidationResult;
+declare function exportEvidencePackJson(pack: ZansnEvidencePack, space?: number): string;
+declare function exportEvidencePackMarkdown(pack: ZansnEvidencePack): string;
+declare function toOpenTelemetryAttributes(event: ZansnTraceEvent): ZansnMetadata;
+declare const zansn: Readonly<{
+    brand: "Zansn Labs";
+    domain: "https://zansn.ai";
+    category: "AI assurance infrastructure";
+    package: "zansn";
+    status: "local-first developer starter kit";
+    schemas: Readonly<{
+        evidencePack: "zansn.evidence-pack.v0";
+        evidenceRecord: "zansn.evidence-record.v0";
+    }>;
+}>;
+
+export { ZANSN_EVIDENCE_PACK_SCHEMA, ZANSN_EVIDENCE_RECORD_SCHEMA, type ZansnAgentResult, ZansnClient, type ZansnClientOptions, type ZansnEvidencePack, type ZansnEvidenceRecord, type ZansnEvidenceSummary, type ZansnFinding, type ZansnFindingKind, type ZansnMetadata, type ZansnPolicy, type ZansnReadiness, type ZansnRunContext, type ZansnRunOptions, type ZansnSeverity, type ZansnTask, type ZansnTaskResult, type ZansnToolCall, type ZansnTraceEvent, type ZansnTraceInput, type ZansnTraceType, type ZansnUsage, type ZansnValidationResult, createEvidenceRecord, ZansnClient as default, exportEvidencePackJson, exportEvidencePackMarkdown, toOpenTelemetryAttributes, validateEvidencePack, zansn };

package/dist/index.js

@@ -0,0 +1,536 @@
+// src/index.ts
+var ZANSN_EVIDENCE_PACK_SCHEMA = "zansn.evidence-pack.v0";
+var ZANSN_EVIDENCE_RECORD_SCHEMA = "zansn.evidence-record.v0";
+var ZansnClient = class {
+  organization;
+  defaultPolicy;
+  metadata;
+  constructor(options = {}) {
+    this.organization = options.organization ?? "Zansn Labs";
+    this.defaultPolicy = options.defaultPolicy ?? {};
+    this.metadata = freezeMetadata(options.metadata);
+  }
+  async runEvaluation(options) {
+    assertNonEmptyString(options.projectId, "ZansnClient.runEvaluation requires projectId.");
+    if (!Array.isArray(options.tasks) || options.tasks.length === 0) {
+      throw new Error("ZansnClient.runEvaluation requires at least one task.");
+    }
+    const runId = createId("zan-run");
+    const experimentId = options.experimentId ?? createId("zan-exp");
+    const createdAt = nowIso();
+    const policy = mergePolicy(this.defaultPolicy, options.policy);
+    const traces = [];
+    const findings = [];
+    const taskResults = [];
+    for (const task of options.tasks) {
+      assertNonEmptyString(task.id, "Every Zansn task requires a stable id.");
+      const taskStart = performanceNow();
+      const taskFindings = [];
+      const recordEvent = (event) => {
+        const traceEvent = createTraceEvent(runId, task.id, event);
+        traces.push(traceEvent);
+        return traceEvent;
+      };
+      recordEvent({
+        type: "task",
+        name: "zansn.task.start",
+        attributes: {
+          "zansn.organization": this.organization,
+          "zansn.project.id": options.projectId,
+          "zansn.experiment.id": experimentId,
+          "zansn.task.id": task.id
+        }
+      });
+      let result;
+      let runtimeError;
+      try {
+        const rawResult = await options.execute(task, {
+          runId,
+          taskId: task.id,
+          recordEvent
+        });
+        result = normalizeAgentResult(rawResult);
+      } catch (error) {
+        runtimeError = errorToMessage(error);
+        result = { output: void 0 };
+        taskFindings.push({
+          id: createId("zan-finding"),
+          kind: "runtime",
+          severity: "critical",
+          taskId: task.id,
+          title: "Agent execution failed",
+          detail: runtimeError,
+          evidence: { error: runtimeError }
+        });
+      }
+      const durationMs = performanceNow() - taskStart;
+      const usage = normalizeUsage(result.usage);
+      for (const trace of result.traces ?? []) {
+        traces.push(createTraceEvent(runId, task.id, trace));
+      }
+      for (const toolCall of result.toolCalls ?? []) {
+        const toolFinding = evaluateToolPolicy(task.id, toolCall, policy);
+        if (toolFinding) {
+          taskFindings.push(toolFinding);
+        }
+        traces.push(toolCallToTrace(runId, task.id, toolCall));
+      }
+      taskFindings.push(...evaluatePrivacyBoundary(task.id, result, policy));
+      taskFindings.push(...evaluateCostAndLatency(task.id, usage, durationMs, policy));
+      const score = runtimeError ? 0 : options.score ? await options.score({ task, result }) : defaultExactMatchScore(task.expected, result.output);
+      const boundedScore = clampScore(score);
+      const minimumScore = policy.minimumScore ?? 1;
+      if (boundedScore < minimumScore && !runtimeError) {
+        taskFindings.push({
+          id: createId("zan-finding"),
+          kind: "evaluation",
+          severity: "medium",
+          taskId: task.id,
+          title: "Task score below policy threshold",
+          detail: `Task scored ${boundedScore}; configured threshold is ${minimumScore}.`,
+          evidence: { score: boundedScore, minimumScore }
+        });
+      }
+      const readiness = determineReadiness(taskFindings, boundedScore, minimumScore);
+      const taskResult = {
+        taskId: task.id,
+        passed: readiness === "ready",
+        score: boundedScore,
+        readiness,
+        durationMs,
+        usage,
+        findings: taskFindings,
+        metadata: freezeMetadata(task.metadata)
+      };
+      if (runtimeError) {
+        taskResult.error = runtimeError;
+      } else {
+        taskResult.output = result.output;
+      }
+      taskResults.push(taskResult);
+      findings.push(...taskFindings);
+      recordEvent({
+        type: "task",
+        name: "zansn.task.complete",
+        attributes: {
+          "zansn.task.readiness": readiness,
+          "zansn.task.score": boundedScore,
+          "zansn.task.duration_ms": durationMs,
+          "zansn.findings.count": taskFindings.length
+        }
+      });
+    }
+    const pack = {
+      schema: ZANSN_EVIDENCE_PACK_SCHEMA,
+      runId,
+      projectId: options.projectId,
+      experimentId,
+      name: options.name ?? "Zansn local AI assurance evaluation",
+      createdAt,
+      completedAt: nowIso(),
+      metadata: freezeMetadata({
+        ...this.metadata,
+        ...options.metadata,
+        "zansn.package": "zansn",
+        "zansn.mode": "local-first"
+      }),
+      summary: summarize(taskResults, findings),
+      taskResults,
+      traces,
+      findings
+    };
+    if (options.description) {
+      pack.description = options.description;
+    }
+    return deepFreeze(pack);
+  }
+};
+function createEvidenceRecord(input) {
+  assertNonEmptyString(input.projectId, "createEvidenceRecord requires projectId.");
+  assertNonEmptyString(input.summary, "createEvidenceRecord requires summary.");
+  return deepFreeze({
+    schema: ZANSN_EVIDENCE_RECORD_SCHEMA,
+    id: createId("zan-ev"),
+    projectId: input.projectId,
+    experimentId: input.experimentId ?? createId("zan-exp"),
+    createdAt: nowIso(),
+    summary: input.summary,
+    metadata: freezeMetadata(input.metadata)
+  });
+}
+function validateEvidencePack(value) {
+  const errors = [];
+  if (!isRecord(value)) {
+    return { valid: false, errors: ["Evidence pack must be an object."] };
+  }
+  if (value.schema !== ZANSN_EVIDENCE_PACK_SCHEMA) {
+    errors.push(`schema must be ${ZANSN_EVIDENCE_PACK_SCHEMA}.`);
+  }
+  for (const key of ["runId", "projectId", "experimentId", "name", "createdAt", "completedAt"]) {
+    if (typeof value[key] !== "string" || value[key].length === 0) {
+      errors.push(`${key} must be a non-empty string.`);
+    }
+  }
+  if (!isRecord(value.summary)) {
+    errors.push("summary must be an object.");
+  }
+  if (!Array.isArray(value.taskResults)) {
+    errors.push("taskResults must be an array.");
+  }
+  if (!Array.isArray(value.traces)) {
+    errors.push("traces must be an array.");
+  }
+  if (!Array.isArray(value.findings)) {
+    errors.push("findings must be an array.");
+  }
+  return { valid: errors.length === 0, errors };
+}
+function exportEvidencePackJson(pack, space = 2) {
+  return `${stableStringify(pack, space)}
+`;
+}
+function exportEvidencePackMarkdown(pack) {
+  const validation = validateEvidencePack(pack);
+  if (!validation.valid) {
+    throw new Error(`Cannot export invalid Zansn evidence pack: ${validation.errors.join(" ")}`);
+  }
+  const findings = pack.findings.length === 0 ? "No findings recorded." : pack.findings.map((finding) => `- [${finding.severity}] ${finding.kind}: ${finding.title}${finding.taskId ? ` (${finding.taskId})` : ""}`).join("\n");
+  const tasks = pack.taskResults.map((task) => `- ${task.taskId}: ${task.readiness}, score ${formatNumber(task.score)}, ${Math.round(task.durationMs)} ms`).join("\n");
+  return [
+    `# Zansn Evidence Pack: ${pack.name}`,
+    "",
+    `Schema: \`${pack.schema}\``,
+    `Run ID: \`${pack.runId}\``,
+    `Project ID: \`${pack.projectId}\``,
+    `Experiment ID: \`${pack.experimentId}\``,
+    `Created: ${pack.createdAt}`,
+    `Completed: ${pack.completedAt}`,
+    "",
+    "## Summary",
+    "",
+    `- Readiness: ${pack.summary.readiness}`,
+    `- Tasks: ${pack.summary.tasks}`,
+    `- Passed: ${pack.summary.passed}`,
+    `- Failed: ${pack.summary.failed}`,
+    `- Blocked: ${pack.summary.blocked}`,
+    `- Pass rate: ${formatNumber(pack.summary.passRate)}`,
+    `- Average score: ${formatNumber(pack.summary.averageScore)}`,
+    `- Total tokens: ${pack.summary.totalTokens}`,
+    `- Estimated cost USD: ${formatNumber(pack.summary.totalEstimatedCostUsd)}`,
+    `- p50 latency ms: ${Math.round(pack.summary.p50LatencyMs)}`,
+    `- p95 latency ms: ${Math.round(pack.summary.p95LatencyMs)}`,
+    `- Highest severity: ${pack.summary.highestSeverity}`,
+    "",
+    "## Tasks",
+    "",
+    tasks || "No tasks recorded.",
+    "",
+    "## Findings",
+    "",
+    findings,
+    "",
+    "## Trace Count",
+    "",
+    `${pack.traces.length} trace events recorded.`,
+    ""
+  ].join("\n");
+}
+function toOpenTelemetryAttributes(event) {
+  return {
+    "service.name": "zansn",
+    "zansn.run.id": event.runId,
+    "zansn.task.id": event.taskId,
+    "zansn.trace.id": event.id,
+    "zansn.trace.type": event.type,
+    "gen_ai.operation.name": event.type === "tool" ? "execute_tool" : "invoke_agent",
+    ...event.attributes
+  };
+}
+var zansn = Object.freeze({
+  brand: "Zansn Labs",
+  domain: "https://zansn.ai",
+  category: "AI assurance infrastructure",
+  package: "zansn",
+  status: "local-first developer starter kit",
+  schemas: Object.freeze({
+    evidencePack: ZANSN_EVIDENCE_PACK_SCHEMA,
+    evidenceRecord: ZANSN_EVIDENCE_RECORD_SCHEMA
+  })
+});
+function createTraceEvent(runId, taskId, input) {
+  const startedAt = input.startedAt ?? nowIso();
+  const event = {
+    id: createId("zan-trace"),
+    runId,
+    taskId,
+    type: input.type,
+    name: input.name,
+    startedAt,
+    attributes: freezeMetadata(input.attributes)
+  };
+  if (input.endedAt) {
+    event.endedAt = input.endedAt;
+  }
+  const durationMs = input.durationMs ?? (input.endedAt ? Date.parse(input.endedAt) - Date.parse(startedAt) : void 0);
+  if (durationMs !== void 0 && Number.isFinite(durationMs)) {
+    event.durationMs = Math.max(0, durationMs);
+  }
+  return event;
+}
+function normalizeAgentResult(value) {
+  if (isRecord(value) && "output" in value) {
+    return value;
+  }
+  return { output: value };
+}
+function normalizeUsage(usage = {}) {
+  const inputTokens = clampNonNegative(usage.inputTokens);
+  const outputTokens = clampNonNegative(usage.outputTokens);
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: clampNonNegative(usage.totalTokens ?? inputTokens + outputTokens),
+    estimatedCostUsd: clampNonNegative(usage.estimatedCostUsd)
+  };
+}
+function evaluateToolPolicy(taskId, toolCall, policy) {
+  const blocked = policy.blockedTools?.includes(toolCall.name);
+  const outsideAllowList = policy.allowedTools !== void 0 && !policy.allowedTools.includes(toolCall.name);
+  if (!blocked && !outsideAllowList) {
+    return void 0;
+  }
+  return {
+    id: createId("zan-finding"),
+    kind: "security",
+    severity: blocked ? "high" : "medium",
+    taskId,
+    title: blocked ? "Blocked tool was called" : "Tool call outside allow list",
+    detail: `Agent attempted to call tool "${toolCall.name}".`,
+    evidence: { toolCall }
+  };
+}
+function evaluatePrivacyBoundary(taskId, result, policy) {
+  const patterns = policy.sensitiveDataPatterns ?? [];
+  if (patterns.length === 0) {
+    return [];
+  }
+  const serialized = stableStringify(result.output);
+  return patterns.filter((pattern) => {
+    pattern.lastIndex = 0;
+    return pattern.test(serialized);
+  }).map((pattern) => ({
+    id: createId("zan-finding"),
+    kind: "privacy",
+    severity: "high",
+    taskId,
+    title: "Sensitive data pattern detected in output",
+    detail: "Agent output matched a configured sensitive data boundary pattern.",
+    evidence: { pattern: pattern.source }
+  }));
+}
+function evaluateCostAndLatency(taskId, usage, durationMs, policy) {
+  const findings = [];
+  if (policy.maxEstimatedCostUsd !== void 0 && usage.estimatedCostUsd > policy.maxEstimatedCostUsd) {
+    findings.push({
+      id: createId("zan-finding"),
+      kind: "cost",
+      severity: "medium",
+      taskId,
+      title: "Estimated cost exceeded policy",
+      detail: `Task estimated cost ${usage.estimatedCostUsd} USD exceeded limit ${policy.maxEstimatedCostUsd} USD.`,
+      evidence: { usage }
+    });
+  }
+  if (policy.maxLatencyMs !== void 0 && durationMs > policy.maxLatencyMs) {
+    findings.push({
+      id: createId("zan-finding"),
+      kind: "latency",
+      severity: "medium",
+      taskId,
+      title: "Latency exceeded policy",
+      detail: `Task latency ${Math.round(durationMs)} ms exceeded limit ${policy.maxLatencyMs} ms.`,
+      evidence: { durationMs }
+    });
+  }
+  return findings;
+}
+function toolCallToTrace(runId, taskId, toolCall) {
+  const input = {
+    type: "tool",
+    name: toolCall.name,
+    attributes: {
+      "gen_ai.tool.name": toolCall.name,
+      "gen_ai.tool.type": "function",
+      "zansn.tool.id": toolCall.id,
+      "zansn.tool.status": toolCall.status ?? "ok",
+      "zansn.tool.arguments": toolCall.arguments,
+      "zansn.tool.result": toolCall.result,
+      ...toolCall.metadata
+    }
+  };
+  if (toolCall.startedAt) {
+    input.startedAt = toolCall.startedAt;
+  }
+  if (toolCall.endedAt) {
+    input.endedAt = toolCall.endedAt;
+  }
+  return createTraceEvent(runId, taskId, input);
+}
+function summarize(results, findings) {
+  const latencies = results.map((result) => result.durationMs).sort((a, b) => a - b);
+  const passed = results.filter((result) => result.passed).length;
+  const blocked = results.filter((result) => result.readiness === "blocked").length;
+  const totalEstimatedCostUsd = results.reduce((sum, result) => sum + result.usage.estimatedCostUsd, 0);
+  const totalTokens = results.reduce((sum, result) => sum + result.usage.totalTokens, 0);
+  const averageScore = results.length === 0 ? 0 : results.reduce((sum, result) => sum + result.score, 0) / results.length;
+  const highestSeverity = highestFindingSeverity(findings);
+  return {
+    tasks: results.length,
+    passed,
+    failed: results.length - passed,
+    blocked,
+    passRate: results.length === 0 ? 0 : passed / results.length,
+    averageScore,
+    totalEstimatedCostUsd,
+    totalTokens,
+    p50LatencyMs: percentile(latencies, 0.5),
+    p95LatencyMs: percentile(latencies, 0.95),
+    highestSeverity,
+    readiness: determinePackReadiness(results, highestSeverity)
+  };
+}
+function determineReadiness(findings, score, minimumScore) {
+  if (findings.some((finding) => finding.severity === "critical" || finding.severity === "high")) {
+    return "blocked";
+  }
+  if (findings.length > 0 || score < minimumScore) {
+    return "review";
+  }
+  return "ready";
+}
+function determinePackReadiness(results, highestSeverity) {
+  if (highestSeverity === "critical" || highestSeverity === "high" || results.some((result) => result.readiness === "blocked")) {
+    return "blocked";
+  }
+  if (highestSeverity !== "info" || results.some((result) => result.readiness === "review")) {
+    return "review";
+  }
+  return "ready";
+}
+function highestFindingSeverity(findings) {
+  const order = ["info", "low", "medium", "high", "critical"];
+  return findings.reduce((highest, finding) => {
+    return order.indexOf(finding.severity) > order.indexOf(highest) ? finding.severity : highest;
+  }, "info");
+}
+function defaultExactMatchScore(expected, output) {
+  if (expected === void 0) {
+    return 1;
+  }
+  return stableStringify(expected) === stableStringify(output) ? 1 : 0;
+}
+function clampScore(value) {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, Math.min(1, value));
+}
+function clampNonNegative(value) {
+  if (value === void 0 || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, value);
+}
+function mergePolicy(base, override = {}) {
+  const policy = { ...base, ...override };
+  const allowedTools = override.allowedTools ?? base.allowedTools;
+  const blockedTools = override.blockedTools ?? base.blockedTools;
+  const sensitiveDataPatterns = override.sensitiveDataPatterns ?? base.sensitiveDataPatterns;
+  if (allowedTools) {
+    policy.allowedTools = allowedTools;
+  }
+  if (blockedTools) {
+    policy.blockedTools = blockedTools;
+  }
+  if (sensitiveDataPatterns) {
+    policy.sensitiveDataPatterns = sensitiveDataPatterns;
+  }
+  return policy;
+}
+function percentile(values, p) {
+  if (values.length === 0) {
+    return 0;
+  }
+  const index = Math.min(values.length - 1, Math.ceil(values.length * p) - 1);
+  return values[index] ?? 0;
+}
+function createId(prefix) {
+  const random = globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+  return `${prefix}-${random}`;
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function errorToMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function assertNonEmptyString(value, message) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(message);
+  }
+}
+function stableStringify(value, space) {
+  return JSON.stringify(sortForJson(value), null, space);
+}
+function sortForJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortForJson);
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  return Object.keys(value).sort().reduce((acc, key) => {
+    acc[key] = sortForJson(value[key]);
+    return acc;
+  }, {});
+}
+function freezeMetadata(metadata) {
+  return Object.freeze({ ...metadata ?? {} });
+}
+function deepFreeze(value) {
+  if (!isRecord(value) && !Array.isArray(value)) {
+    return value;
+  }
+  Object.freeze(value);
+  for (const item of Object.values(value)) {
+    if ((isRecord(item) || Array.isArray(item)) && !Object.isFrozen(item)) {
+      deepFreeze(item);
+    }
+  }
+  return value;
+}
+function formatNumber(value) {
+  return Number.isInteger(value) ? String(value) : value.toFixed(4).replace(/0+$/, "").replace(/\.$/, "");
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function performanceNow() {
+  return globalThis.performance?.now?.() ?? Date.now();
+}
+var index_default = ZansnClient;
+export {
+  ZANSN_EVIDENCE_PACK_SCHEMA,
+  ZANSN_EVIDENCE_RECORD_SCHEMA,
+  ZansnClient,
+  createEvidenceRecord,
+  index_default as default,
+  exportEvidencePackJson,
+  exportEvidencePackMarkdown,
+  toOpenTelemetryAttributes,
+  validateEvidencePack,
+  zansn
+};

package/examples/basic-evaluation.mjs

@@ -0,0 +1,62 @@
+import {
+  ZansnClient,
+  exportEvidencePackMarkdown,
+  validateEvidencePack
+} from "zansn";
+
+const client = new ZansnClient({
+  defaultPolicy: {
+    allowedTools: ["lookupCustomer"],
+    blockedTools: ["deleteCustomer"],
+    sensitiveDataPatterns: [/sk-[a-z0-9]+/i],
+    maxEstimatedCostUsd: 0.05,
+    maxLatencyMs: 5_000,
+    minimumScore: 1
+  }
+});
+
+const evidence = await client.runEvaluation({
+  projectId: "ZAN-RD-001",
+  experimentId: "ZAN-EXP-001",
+  name: "Customer support agent readiness check",
+  tasks: [
+    {
+      id: "support-001",
+      input: "Check whether ACME has an active support plan.",
+      expected: "active"
+    }
+  ],
+  execute: async (_task, context) => {
+    context.recordEvent({
+      type: "agent",
+      name: "agent.plan",
+      attributes: {
+        step: "lookup_customer_status"
+      }
+    });
+
+    return {
+      output: "active",
+      toolCalls: [
+        {
+          name: "lookupCustomer",
+          arguments: { customer: "ACME" },
+          result: { plan: "active" },
+          status: "ok"
+        }
+      ],
+      usage: {
+        inputTokens: 140,
+        outputTokens: 32,
+        estimatedCostUsd: 0.004
+      }
+    };
+  }
+});
+
+const validation = validateEvidencePack(evidence);
+if (!validation.valid) {
+  throw new Error(validation.errors.join("\n"));
+}
+
+console.log(exportEvidencePackMarkdown(evidence));

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "zansn",
+  "version": "0.1.0",
+  "description": "Local-first AI assurance SDK for evaluating agent workflows and producing evidence packs.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "assets",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "release:check": "npm run typecheck && npm test && npm run build && npm audit --omit=optional && npm pack --dry-run",
+    "publish:dry-run": "npm publish --dry-run",
+    "prepack": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "zansn",
+    "zansn-labs",
+    "ai-assurance",
+    "agent-evaluation",
+    "agent-observability",
+    "agent-tracing",
+    "ai-security",
+    "ai-agents",
+    "llm-evals",
+    "evidence-pack",
+    "local-first-ai",
+    "opentelemetry"
+  ],
+  "author": "Zansn Labs",
+  "license": "Apache-2.0",
+  "homepage": "https://zansn.ai",
+  "bugs": {
+    "url": "https://zansn.ai/contact"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://zansn.ai"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "overrides": {
+    "esbuild": "^0.28.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}