npm - @tenova/swt3-ai - Versions diffs - 0.2.9 → 0.3.0 - Mend

@tenova/swt3-ai 0.2.9 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +241 -244
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,4 +1,4 @@
-Deterministic AI Governance for production agents. Zero latency. Zero data retention.
+Witness your AI. Prove it followed the rules. Cryptographic accountability for every inference, tool call, and resource access.
 [![npm](https://img.shields.io/npm/v/@tenova/swt3-ai)](https://www.npmjs.com/package/@tenova/swt3-ai)
 [![Downloads](https://img.shields.io/npm/dm/@tenova/swt3-ai)](https://www.npmjs.com/package/@tenova/swt3-ai)
@@ -6,26 +6,22 @@ Deterministic AI Governance for production agents. Zero latency. Zero data reten
 # @tenova/swt3-ai
-**SWT3 AI Witness SDK for TypeScript**: continuous, cryptographic attestation for AI systems. Prove your models are running approved weights, safety guardrails are active, and inferences are traceable. All without a single prompt or response ever leaving your infrastructure.
+**SWT3 AI Witness SDK for TypeScript**: tamper-proof evidence that your AI is doing what you say it does. Every inference hashed. Every tool call recorded. Every resource access checked against scope. No prompts or responses ever leave your infrastructure.
 Works with OpenAI, Anthropic, Vercel AI SDK, and any OpenAI-compatible endpoint (vLLM, Ollama, Azure, Llama.cpp).
-## Why SWT3?
+The EU AI Act takes effect **August 2, 2026**. When regulators ask "prove your AI followed the rules," you need more than logs. You need cryptographic proof.
-AI agents are making production decisions, but when regulators ask "prove your AI followed the rules," most teams have nothing but logs and dashboards. SWT3 produces cryptographic, tamper-proof evidence of every AI action. No prompt data leaves your infrastructure. The EU AI Act (enforcement: August 2, 2026) requires exactly this.
-## See It Work in 10 Seconds
-No API keys. No account. No network calls.
+## See It Work (No Account Needed)
 ```bash
 npm install @tenova/swt3-ai
 npx swt3-demo
 ```
-You'll see the full SWT3 witnessing pipeline: hash, extract, clear, anchor, verify — plus a **Regulatory Coverage Summary** mapping each procedure to EU AI Act articles. The demo shows 3/12 obligations covered, with the 9 uncovered gaps listed by article citation. When you're ready to close those gaps, keep reading.
+The demo runs the full pipeline locally: hash, extract, clear, anchor, verify. It shows a Regulatory Coverage Summary mapping each check to EU AI Act articles, with gaps highlighted. No API keys, no network calls.
-## Three Lines of Code
+## Three Lines to Start Witnessing
 ### OpenAI
@@ -34,21 +30,21 @@ import { Witness } from "@tenova/swt3-ai";
 import OpenAI from "openai";
 const witness = new Witness({
-  endpoint: "https://sovereign.tenova.io",
+  endpoint: "https://your-witness-endpoint.example.com",
   apiKey: "axm_live_...",
-  tenantId: "YOUR_ENCLAVE",
+  tenantId: "YOUR_TENANT",
 });
 const client = witness.wrap(new OpenAI()) as OpenAI;
-// Non-streaming, works exactly as before
+// Non-streaming
 const response = await client.chat.completions.create({
   model: "gpt-4o",
   messages: [{ role: "user", content: "Summarize this contract..." }],
 });
 console.log(response.choices[0].message.content);
-// Streaming, also works. Chunks arrive in real-time, witnessing happens after.
+// Streaming works too. Chunks arrive in real-time, witnessing happens after.
 const stream = await client.chat.completions.create({
   model: "gpt-4o",
   messages: [{ role: "user", content: "Explain quantum computing" }],
@@ -66,9 +62,9 @@ import { Witness } from "@tenova/swt3-ai";
 import Anthropic from "@anthropic-ai/sdk";
 const witness = new Witness({
-  endpoint: "https://sovereign.tenova.io",
+  endpoint: "https://your-witness-endpoint.example.com",
   apiKey: "axm_live_...",
-  tenantId: "YOUR_ENCLAVE",
+  tenantId: "YOUR_TENANT",
 });
 const client = witness.wrap(new Anthropic()) as Anthropic;
@@ -78,17 +74,6 @@ const message = await client.messages.create({
   max_tokens: 1024,
   messages: [{ role: "user", content: "Draft a compliance memo" }],
 });
-// Streaming with Anthropic
-const stream = await client.messages.create({
-  model: "claude-sonnet-4-20250514",
-  max_tokens: 1024,
-  messages: [{ role: "user", content: "Analyze this dataset" }],
-  stream: true,
-});
-for await (const event of stream) {
-  // events arrive in real-time, witnessing happens after stream ends
-}
 ```
 ### Vercel AI SDK (Next.js / React)
@@ -99,9 +84,9 @@ import { streamText } from "ai";
 import { openai } from "@ai-sdk/openai";
 const witness = new Witness({
-  endpoint: "https://sovereign.tenova.io",
+  endpoint: "https://your-witness-endpoint.example.com",
   apiKey: "axm_live_...",
-  tenantId: "YOUR_ENCLAVE",
+  tenantId: "YOUR_TENANT",
 });
 const prompt = "Summarize this contract for the board";
@@ -111,303 +96,315 @@ const result = await streamText({
   prompt,
   onFinish: witness.vercelOnFinish({ promptText: prompt }),
 });
-// Works with any Vercel AI SDK provider:OpenAI, Anthropic, Google, Mistral, custom
 ```
-The `onFinish` hook is framework-idiomatic: no wrapping, no proxying, no monkey-patching. It fires after the stream completes and receives a normalized result regardless of provider.
+The `onFinish` hook is framework-native. No wrapping, no proxying. It fires after the stream completes and works with any Vercel AI SDK provider.
-## Sovereign Cloud Support
-The SDK works out-of-the-box with any OpenAI-compatible endpoint. Run Llama 3 on vLLM, Mistral on Ollama, or any model behind an OpenAI-compatible API:every inference is witnessed identically.
+## What the SDK Does
-```typescript
-// vLLM with Llama 3, sovereign cloud, your hardware
-const client = witness.wrap(
-  new OpenAI({ baseURL: "http://gpu-cluster.internal:8000/v1" }),
-) as OpenAI;
-const response = await client.chat.completions.create({
-  model: "meta-llama/Meta-Llama-3-70B-Instruct",
-  messages: [{ role: "user", content: "Classify this threat indicator" }],
-});
-// Same SWT3 anchor, same ledger, same audit trail:regardless of where the model runs
+When your AI makes a call, the SDK:
-// Ollama (local development)
-const localClient = witness.wrap(
-  new OpenAI({ baseURL: "http://localhost:11434/v1" }),
-) as OpenAI;
+1. **Hashes** the prompt and response locally using SHA-256 (raw text never leaves your machine)
+2. **Extracts** numeric factors: model version, latency, token count, guardrail status
+3. **Clears** sensitive metadata based on your clearing level (you control what goes on the wire)
+4. **Anchors** the factors into a cryptographic fingerprint anyone can independently verify
+5. **Buffers** and flushes anchors in the background (median overhead: under 1ms)
+6. **Returns** your original response completely untouched
-// Azure OpenAI (enterprise deployment)
-const azureClient = witness.wrap(
-  new OpenAI({
-    apiKey: process.env.AZURE_OPENAI_KEY,
-    baseURL: "https://your-resource.openai.azure.com/openai/deployments/gpt-4o",
-  }),
-) as OpenAI;
-```
+For streaming: chunks arrive to the developer in real-time. The SDK accumulates content in the background and witnesses after the stream completes.
-## Quick Start (Try It Locally)
+## Witness Agent Tool Calls
-Want to see the SDK work before connecting to a live endpoint? Use `factorHandoff` to write witness anchors to local JSON files. No account needed.
+If your AI agent calls tools or functions, wrap them to create a record of every invocation:
 ```typescript
-import { Witness } from "@tenova/swt3-ai";
-import OpenAI from "openai";
+const search = witness.wrapTool(
+  (query: string) => db.execute(query),
+  "search_database"
+);
-const witness = new Witness({
-  endpoint: "https://sovereign.tenova.io",
-  apiKey: "test",                // any string, handoff runs before network flush
-  tenantId: "LOCAL_TEST",
-  factorHandoff: "file",         // write anchors to ./swt3-handoff/ as JSON
-});
-const client = witness.wrap(new OpenAI()) as OpenAI;
-const response = await client.chat.completions.create({
-  model: "gpt-4o",
-  messages: [{ role: "user", content: "What is the EU AI Act?" }],
-});
-console.log(response.choices[0].message.content);
-// Check ./swt3-handoff/ - you'll see a JSON file per inference with:
-//   - SHA-256 fingerprint
-//   - Model ID, latency, token count
-//   - Clearing level applied
-//   - Full factor data for independent verification
+const results = await search("SELECT * FROM transactions WHERE amount > 10000");
+// An AI-TOOL.1 anchor is minted recording: tool name, latency, success/failure
 ```
-When you're ready for production, [create a free account](https://sovereign.tenova.io/signup?ref=sdk) to get your tenant ID and API key. Point the SDK at your enclave and every inference is witnessed, anchored, and verifiable.
+When an auditor asks "what tools did your agent use?" you have the cryptographic record.
-## Local SDK vs Axiom Engine
+## Witness Agent Resource Access
-| Capability | Local SDK | + Axiom Engine (free) |
-|---|---|---|
-| Mint anchors | ✓ | ✓ |
-| Verify one anchor | ✓ | ✓ |
-| Evidence retention | 0 (files on disk) | 7 days (free) / 90 days (Pro) |
-| Compliance dashboard | — | ✓ |
-| Auditor share links | — | ✓ (Pro) |
-| EU AI Act conformity | — | ✓ (Pro) |
-| Compliance Passport | — | ✓ (Pro) |
-| Enclave integrity proof | — | ✓ (Enclave) |
-| **Survives an audit** | **No** | **Yes** |
+New in v0.2.10. Wrap any function your agent uses to access external resources. The SDK records what was accessed and whether it was within the agent's declared scope:
+```typescript
+const queryCustomers = witness.wrapAccess(
+  (sql: string) => db.execute(sql),
+  "customer-database",      // resource name
+  "read-only analytics"     // declared authorization scope
+);
+const results = await queryCustomers("SELECT name FROM customers");
+// An AI-ACC.1 anchor is minted recording:
+//   - Was it accessed? (yes)
+//   - Was it within scope? (yes)
+//   - Was access granted? (yes)
+```
-> **Local anchors prove it to you. Axiom proves it to your auditor.**
-> [Create a free account →](https://sovereign.tenova.io/signup?ref=sdk)
+If the agent tries to access something outside its declared scope, the anchor records a FAIL verdict. When a CISO asks "can you prove your AI agent only accessed what it was authorized to access?" this is the answer.
-## What Happens Per Inference
+## Detect Instruction Drift
-1. **Intercept**: ES6 Proxy wraps your AI client transparently
-2. **Hash**: Prompts and responses are SHA-256 hashed in-process
-3. **Extract**: Model hash, latency, token count, refusal status as numeric factors
-4. **Clear**: Raw text is purged from the wire payload (configurable clearing level)
-5. **Buffer**: Factors queued in background, flushed to the SWT3 ledger asynchronously
-6. **Return**: Your original response returns untouched. Witnessing runs in a background thread — median overhead is <1ms on the hot path (hash + buffer, no network call)
+New in v0.2.10. The SDK separately hashes the system prompt (base instructions) for each inference. If your agent's instructions change between audit periods, the hash changes and the platform flags it as instruction drift.
-For streaming: chunks arrive to the developer in real-time. The SDK accumulates content in the background and witnesses after the stream completes.
+This happens automatically. No configuration needed. The system prompt hash is extracted from:
+- OpenAI: messages where `role === "system"`
+- Anthropic: the `system` parameter
-## Clearing Levels
+The hash is included at clearing levels 0 and 1, stripped at levels 2 and 3.
-| Level | Name | On the Wire | Use Case |
-|-------|------|------------|----------|
-| 0 | Analytics | Hashes + factors + model + provider + guardrails | Internal analytics |
-| 1 | Standard | Hashes + factors + model + provider | **Default.** Production apps |
-| 2 | Sensitive | Hashes + factors + model only | Healthcare, legal, PII |
-| 3 | Classified | Numeric factors only. Model ID hashed. | Defense, air-gapped |
+## Agent Identity
-At Level 1+, raw prompts and responses **never leave your infrastructure**. The witness endpoint is a "Blind Registrar":it stores cryptographic proofs, not data.
+Bind a unique identity to every anchor your agent produces:
 ```typescript
-// Healthcare deployment: Level 2
 const witness = new Witness({
-  endpoint: "https://sovereign.tenova.io",
-  apiKey: "axm_live_...",
-  tenantId: "HOSPITAL_ENCLAVE",
-  clearingLevel: 2,
+  endpoint: "...",
+  apiKey: "axm_...",
+  tenantId: "...",
+  agentId: "fraud-detector-prod",
+  signingKey: "swt3_sk_...",  // HMAC-SHA256 signing for non-repudiation
 });
 ```
+The `agentId` survives all clearing levels. The `signingKey` produces a cryptographic signature on every anchor, proving which agent instance created it. This enables:
+- Per-agent compliance passports
+- Fleet-wide governance dashboards
+- Agent-scoped evidence packages for auditors
 ## What Gets Witnessed
-| Procedure | What It Proves | Regulatory Mapping |
-|-----------|---------------|-------------------|
-| AI-INF.1 | Inference provenance (prompt + response hashed) | EU AI Act Art. 12 |
-| AI-INF.2 | Latency within threshold (detects model swaps) | NIST AI RMF MEASURE 2.6 |
-| AI-MDL.1 | Model hash matches approved version | EU AI Act Art. 9 |
-| AI-MDL.2 | Model version identifier recorded | EU AI Act Art. 72 |
-| AI-GRD.1 | Required guardrails were active | NIST AI RMF MANAGE 4.1 |
-| AI-GRD.2 | No content filter / refusal triggered | EU AI Act Art. 9 |
-| AI-TOOL.1 | Agent tool/function call recorded (latency, success) | NIST AI RMF MANAGE 4.1 |
-| AI-ID.1 | Witness instance identity attested (agent accountability) | EU AI Act Art. 13 |
-## View an Anchor
-A Level 1 anchor for AI-INF.1 (Inference Provenance). This is what reaches the witness ledger. No prompts, no responses, just cryptographic proof.
-```json
-{
-  "procedure_id": "AI-INF.1",
-  "factor_a": 1,
-  "factor_b": 1,
-  "factor_c": 0,
-  "clearing_level": 1,
-  "anchor_fingerprint": "c059eb5938c0",
-  "anchor_epoch": 1774800000,
-  "fingerprint_timestamp_ms": 1774800000000,
-  "ai_prompt_hash": "315f5bdb76d078c4",
-  "ai_response_hash": "a1b2c3d4e5f60718",
-  "ai_latency_ms": 842,
-  "ai_model_id": "gpt-4o",
-  "ai_context": {
-    "provider": "openai",
-    "guardrails": ["content-filter", "pii-redaction"]
-  }
-}
-```
+Each inference produces anchors for these checks. Every check maps to a regulation.
-The `anchor_fingerprint` is computed from `SHA256("WITNESS:{tenant}:{procedure}:{fa}:{fb}:{fc}:{ts}")`. Anyone with the factors can independently verify the math.
+| Check | What It Proves | Plain English | Regulation |
+|-------|---------------|---------------|------------|
+| AI-INF.1 | Prompt and response were captured | "Was the inference logged?" | EU AI Act Art. 12 |
+| AI-INF.2 | Latency was within threshold | "Was response time acceptable?" | NIST AI RMF MEASURE 2.6 |
+| AI-MDL.1 | Deployed model matches approved hash | "Is this the right model?" | EU AI Act Art. 9 |
+| AI-MDL.2 | Model version was recorded | "Is the model version tracked?" | EU AI Act Art. 72 |
+| AI-GRD.1 | Required safety guardrails were active | "Are enough guardrails running?" | NIST AI RMF MANAGE 4.1 |
+| AI-GRD.2 | No refusal or content filter triggered | "Did a safety filter trigger?" | EU AI Act Art. 9 |
+| AI-TOOL.1 | Tool/function call was recorded | "Did the tool call succeed?" | NIST AI RMF MANAGE 4.1 |
+| AI-ACC.1 | Resource access was within scope | "Was the access authorized?" | EU AI Act Art. 14 |
+| AI-ID.1 | Agent identity was attested | "Is the agent identified?" | EU AI Act Art. 13 |
-## Resilience (Flight Recorder)
+## How Verdicts Work
-If the witness endpoint is unreachable, payloads move to a dead-letter queue instead of being dropped. When connectivity is restored, the backlog drains automatically.
+Every anchor carries three numbers:
-```typescript
-const witness = new Witness({
-  endpoint: "...",
-  apiKey: "axm_...",
-  tenantId: "...",
-  bufferSize: 50,       // flush every 50 anchors
-  flushInterval: 10,    // or every 10 seconds
-  maxRetries: 5,        // retry before dead-lettering
-});
-```
+- **factor_a** = the threshold (what should happen)
+- **factor_b** = the observation (what actually happened)
+- **factor_c** = context (extra detail)
-## Zero Lock-in
+The verdict is a simple comparison. No AI, no probability. Just math.
-Remove the `witness.wrap()` call. Your code works exactly as before. Anchors already minted remain in the ledger.
+### Reading an Anchor
-## Cross-Language Parity
+```
+Check: AI-GRD.1    factor_a: 2    factor_b: 3    factor_c: 1    Verdict: PASS
-This SDK produces **identical SWT3 fingerprints** to the Python SDK (`swt3-ai`) and the Axiom ingestion endpoint. A unified audit trail across your entire stack:
+Translation: "We required 2 guardrails. 3 were active. All passed."
+```
-| Layer | Language | Package |
-|-------|----------|---------|
-| Backend services | Python | `swt3-ai` |
-| API routes / Edge | TypeScript | `@tenova/swt3-ai` |
-| Frontend (Next.js) | TypeScript | `@tenova/swt3-ai` + Vercel AI SDK |
-| CLI / scripts | Python | `swt3-ai` |
+```
+Check: AI-ACC.1    factor_a: 1    factor_b: 0    factor_c: 0    Verdict: FAIL
-10 cross-language test vectors validated at build time.
+Translation: "Access attempt occurred. Target was outside declared scope. Access denied."
+```
-## Installation
+### Factor Reference
-```bash
-npm install @tenova/swt3-ai
+| Check | factor_a | factor_b | factor_c | Verdict Rule |
+|-------|----------|----------|----------|-------------|
+| AI-INF.1 | 1 (required) | 1 if hashes present | 0 | PASS if b >= a |
+| AI-INF.2 | Latency limit (ms) | Actual latency (ms) | 1 if over limit | PASS if b <= a |
+| AI-MDL.1 | 1 (required) | 1 if hash present | 0 | PASS if b >= a |
+| AI-MDL.2 | 1 (required) | 1 if version recorded | 0 | PASS if b >= a |
+| AI-GRD.1 | Required count | Active count | 1 if all passed | PASS if b >= a |
+| AI-GRD.2 | 1 (clean expected) | 0 if refusal | 0 | PASS if b >= a |
+| AI-TOOL.1 | 1 (called) | Latency (ms) | 1=success, 0=error | PASS if b >= a |
+| AI-ACC.1 | 1 (accessed) | 1=in scope, 0=out | 1=granted, 0=denied | PASS if b >= a |
+| AI-ID.1 | 1 (required) | 1 if identity present | 0 | PASS if b >= a |
-# Peer dependencies (install whichever you use)
-npm install openai          # for OpenAI adapter
-npm install @anthropic-ai/sdk  # for Anthropic adapter
+### Verify Any Anchor From Your Terminal
+```bash
+echo -n "WITNESS:DEMO_TENANT:AI-INF.1:1:1:0:1774800000000" | sha256sum | cut -c1-12
+# Produces a 12-character fingerprint. Compare it to the anchor. If it matches, the anchor is real.
 ```
-## API Reference
+No SDK needed. Works on any machine, any language.
-### `new Witness(options)`
+## Sovereign Cloud Support
-| Option | Default | Description |
-|--------|---------|-------------|
-| `endpoint` | *required* | Witness endpoint URL |
-| `apiKey` | *required* | API key (`axm_*`) |
-| `tenantId` | *required* | Enclave identifier |
-| `clearingLevel` | `1` | Clearing level (0-3) |
-| `bufferSize` | `10` | Flush after N anchors |
-| `flushInterval` | `5` | Flush after N seconds |
-| `timeout` | `10000` | HTTP timeout (ms) |
-| `maxRetries` | `3` | Retries before dead-letter |
-| `guardrailNames` | `[]` | Active guardrail names |
-| `factorHandoff` | - | `"file"` to enable local factor export |
-| `factorHandoffPath` | - | Directory for factor handoff files |
+The SDK works with any OpenAI-compatible endpoint. Run models on your own infrastructure and witness every inference identically:
+```typescript
+// vLLM with Llama 3 on your hardware
+const client = witness.wrap(
+  new OpenAI({ baseURL: "http://gpu-cluster.internal:8000/v1" }),
+) as OpenAI;
-### `witness.wrap(client)`
+// Ollama for local development
+const localClient = witness.wrap(
+  new OpenAI({ baseURL: "http://localhost:11434/v1" }),
+) as OpenAI;
-Returns a Proxy that behaves identically to the original client. Supports OpenAI and Anthropic.
+// Azure OpenAI
+const azureClient = witness.wrap(
+  new OpenAI({
+    apiKey: process.env.AZURE_OPENAI_KEY,
+    baseURL: "https://your-resource.openai.azure.com/openai/deployments/gpt-4o",
+  }),
+) as OpenAI;
+```
-### `witness.vercelOnFinish(options?)`
+Same anchors, same ledger, same audit trail. Regardless of where the model runs.
-Returns an `onFinish` callback for `streamText()` / `generateText()`. Pass `{ promptText }` for full provenance hashing.
+## Clearing Levels (Privacy Control)
-### `witness.flush()`
+You control what leaves your infrastructure. The SDK always returns the full response to your code. Clearing only affects the witness payload.
-Force-flush all buffered payloads. Returns receipts.
+| Level | Name | What Goes on the Wire | Use Case |
+|-------|------|-----------------------|----------|
+| 0 | Analytics | Everything: hashes, factors, model, provider, guardrails, prompt hash | Internal analytics |
+| 1 | Standard | Hashes, factors, model, provider (no raw text ever) | **Default.** Production apps |
+| 2 | Sensitive | Hashes, factors, model only. No provider, no guardrail names | Healthcare, legal, PII |
+| 3 | Classified | Numeric factors only. Model name hashed. Zero metadata | Defense, air-gapped |
-### `witness.stop()`
+```typescript
+const witness = new Witness({
+  endpoint: "...",
+  apiKey: "axm_...",
+  tenantId: "...",
+  clearingLevel: 2, // Sensitive: strips provider and guardrail names
+});
+```
-Stop the witness and flush remaining payloads.
+At every level, raw prompts and responses **never leave your infrastructure**. Only SHA-256 hashes and numeric factors travel on the wire.
-## Factor Handoff (Clearing Level 2+)
+## Local Mode (No Account Needed)
-At Clearing Level 2 or 3, some or all verifiable data is stripped before it reaches the witness endpoint. The Factor Handoff writes your factors to a local directory **before** clearing proceeds. If the write fails, the payload is not transmitted.
+Try the SDK locally before connecting to a live endpoint:
 ```typescript
 const witness = new Witness({
-  endpoint: "https://sovereign.tenova.io",
-  apiKey: "axm_live_...",
-  tenantId: "YOUR_ENCLAVE",
-  clearingLevel: 3,
-  factorHandoff: "file",
-  factorHandoffPath: "/secure/vault/factors/",
+  endpoint: "https://your-witness-endpoint.example.com",
+  apiKey: "test",
+  tenantId: "LOCAL_TEST",
+  factorHandoff: "file", // Writes anchors to ./swt3-handoff/ as JSON
 });
 ```
-Each anchor gets its own JSON file containing the full uncleared factors and metadata for independent re-verification.
+## Local SDK vs Connected
-For the full protocol specification, see the [Factor Handoff Protocol](https://sovereign.tenova.io/docs/factor-handoff-protocol.html).
+| Capability | Local SDK | Connected (free tier) |
+|---|---|---|
+| Mint anchors | Yes | Yes |
+| Verify one anchor | Yes | Yes |
+| Evidence retention | Files on disk | 7 days (free) / 90 days (Pro) |
+| Compliance dashboard | No | Yes |
+| Agent Passport | No | Yes (Pro) |
+| Fleet dashboard | No | Yes (Pro) |
+| EU AI Act conformity | No | Yes (Pro) |
+| Auditor evidence packages | No | Yes (Pro) |
+| Access violation tracking | No | Yes (Pro) |
+| **Survives an audit** | **No** | **Yes** |
-## AI Witness-as-a-Service
+> Local anchors prove it to you. A connected engine proves it to your auditor.
-SWT3 AI Witness is available as a managed service through [Axiom Sovereign Engine](https://tenova.io):
+## Resilience (Flight Recorder)
-| Tier | Retention | Key Features | Price |
-|------|-----------|-------------|-------|
-| **Open** | 7 days | SDK, dashboard, public verify | Free |
-| **Pro** | 90 days | + AI conformity exports, regulatory reports | $499/mo |
-| **Enclave** | 1 year | + OSCAL, Gate API, attestations, webhook feeds | $9,500/mo |
-| **Sovereign** | Custom | + White-glove ATO sprint, mock assessment, on-prem | [Book Assessment](https://calendly.com/tenova-axiom/30min) |
+The SDK never blocks your inference. If the witness endpoint is unreachable, payloads move to a dead-letter queue. When connectivity returns, the backlog drains automatically. Your production system is never affected.
-1,600+ downloads across npm and PyPI. 151 procedures. 13 frameworks. Patent pending.
+```typescript
+const witness = new Witness({
+  endpoint: "...",
+  apiKey: "axm_...",
+  tenantId: "...",
+  bufferSize: 50,       // flush every 50 anchors
+  flushInterval: 10,    // or every 10 seconds
+  maxRetries: 5,        // retry before dead-lettering
+});
+```
-## Ready to Witness Your AI?
+## API Reference
-Get an API key and start witnessing in under 10 minutes:
+### `new Witness(options)`
-- [Create a Free Account](https://sovereign.tenova.io/signup?ref=sdk) - instant API key, start witnessing in 5 minutes
-- [Quickstart Guide](https://sovereign.tenova.io/guides/ai-witness-quickstart.html) - 10-minute integration walkthrough
-- [Book a Strategy Call](https://calendly.com/tenova-axiom/30min) - enterprise, on-prem, or Sovereign tier
+| Option | Default | Description |
+|--------|---------|-------------|
+| `endpoint` | required | Witness endpoint URL |
+| `apiKey` | required | API key (axm_ prefix) |
+| `tenantId` | required | Your tenant identifier |
+| `clearingLevel` | 1 | Privacy level (0-3) |
+| `bufferSize` | 10 | Flush after N anchors |
+| `flushInterval` | 5 | Flush after N seconds |
+| `timeout` | 10000 | HTTP timeout (ms) |
+| `maxRetries` | 3 | Retries before dead-letter |
+| `guardrailNames` | [] | Active guardrail names |
+| `agentId` | - | Agent identity (survives all clearing levels) |
+| `signingKey` | - | HMAC-SHA256 key for payload signing |
+| `factorHandoff` | - | "file" for local factor export |
+| `factorHandoffPath` | - | Directory for handoff files |
+### Methods
+| Method | Description |
+|--------|-------------|
+| `witness.wrap(client)` | Returns a Proxy that behaves identically to the original client. Supports OpenAI and Anthropic. |
+| `witness.wrapTool(fn, name?)` | Wraps a function for tool call witnessing (AI-TOOL.1). |
+| `witness.wrapAccess(fn, resource?, scope?)` | Wraps a function for resource access witnessing (AI-ACC.1). |
+| `witness.vercelOnFinish(opts?)` | Returns an onFinish callback for Vercel AI SDK streamText/generateText. |
+| `witness.flush()` | Force-flush all buffered payloads. Returns receipts. |
+| `witness.stop()` | Stop the witness and flush remaining payloads. |
-## Compliance & Privacy
+## Installation
-Your prompts and responses **never leave your infrastructure**. The SDK computes SHA-256 hashes locally and transmits only irreversible hashes and numeric factors. At Clearing Level 3, even the model name is hashed.
+```bash
+npm install @tenova/swt3-ai
-- [Data Flow and Privacy Architecture](https://github.com/tenova-labs/swt3-ai/blob/main/docs/data-flow.md) - Visual data boundary for legal and DPO review
-- [Clearing & Data Sovereignty Addendum](https://sovereign.tenova.io/terms/clearing-addendum) - Shared responsibility, incident response SLA, regulatory applicability
-- [Air-Gap Deployment Guide](https://github.com/tenova-labs/swt3-ai/blob/main/docs/sovereign-sync.md) - Zero-egress operation, sneakernet sync, offline verification
+# Peer dependencies (install whichever you use)
+npm install openai              # for OpenAI adapter
+npm install @anthropic-ai/sdk   # for Anthropic adapter
+```
-## Documentation
+## Regulatory Coverage
-- [SDK Developer Docs](https://sovereign.tenova.io/docs/) - Quickstart, providers, clearing levels, configuration
-- [Factor Handoff Protocol](https://sovereign.tenova.io/docs/factor-handoff-protocol.html) - How factors are securely transferred to your custody
-- [CMMC Compliance Overlay](https://sovereign.tenova.io/guides/cmmc-overlay.html) - Control mappings for defense industrial base
+The SWT3 AI Witnessing Profile maps to:
----
+- **EU AI Act**: Articles 9, 10, 12, 13, 14, 53, 72
+- **NIST AI RMF**: GOVERN, MAP, MEASURE, MANAGE functions
+- **ISO 42001**: Annex A AI management controls
+- **NIST 800-53**: SI-7 (integrity), AU-2/AU-3 (audit), AC controls
+- **SR 11-7**: Model risk management (financial services)
-## Support the Standard
+## Zero Lock-in
-If you believe AI systems should prove they followed the rules, [give us a star](https://github.com/tenova-labs/swt3-ai). Every star signals that the industry is ready for an accountability standard.
+Remove the `witness.wrap()` call. Your code works exactly as before. Anchors already minted stay in the ledger. There is nothing to undo.
+## Cross-Language Parity
+This SDK produces identical fingerprints to the Python SDK (`swt3-ai`). A unified audit trail across your entire stack, verified by shared test vectors at build time.
+| Layer | Language | Package |
+|-------|----------|---------|
+| Backend services | Python | swt3-ai |
+| API routes / Edge | TypeScript | @tenova/swt3-ai |
+| Frontend (Next.js) | TypeScript | @tenova/swt3-ai + Vercel AI SDK |
+## Privacy
+Your prompts and responses **never leave your infrastructure**. The SDK computes SHA-256 hashes locally and transmits only irreversible hashes and numeric factors. At Clearing Level 3, even the model name is hashed. The witness endpoint is a blind registrar: it stores cryptographic proofs, not your data.
 ---
 *SWT3: Sovereign Witness Traceability. We don't run your models. We witness them.*
-*TeNova: Defining the AI Accountability Standard. One protocol. Zero Integrity Debt. Total Sovereignty.*
 SWT3 and Sovereign Witness Traceability are trademarks of Tenable Nova LLC. Patent pending. Apache 2.0 licensed.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@tenova/swt3-ai",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "SWT3 AI Witness SDK: cryptographic attestation for AI inference",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",