@xproof/xproof 0.1.7 → 0.1.9

package/README.md

@@ -1,5 +1,7 @@
 # xproof
 
+[![npm SDK CI](https://github.com/jasonxkensei/xproof/actions/workflows/npm-sdk.yml/badge.svg?branch=main)](https://github.com/jasonxkensei/xproof/actions/workflows/npm-sdk.yml) [![npm version](https://img.shields.io/npm/v/@xproof/xproof)](https://www.npmjs.com/package/@xproof/xproof) [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+
 On-chain decision provenance for autonomous agents. **WHY before acting. WHAT after.** Timestamps written by the chain, not your agent.
 
 ```bash
@@ -161,6 +163,312 @@ const proof = await client.verifyHash(fileHash);
 console.log(proof.blockchainStatus); // "confirmed" | "pending"
 ```
 
+## Policy Compliance
+
+Check whether a decision meets governance requirements — without fetching the full confidence trail:
+
+```typescript
+import { XProofClient } from "@xproof/xproof";
+import type { PolicyCheckResult } from "@xproof/xproof";
+
+const client = new XProofClient({ apiKey: "pm_your_key" });
+
+const result: PolicyCheckResult = await client.getPolicyCheck("trade-xyz-2026");
+
+if (result.policyCompliant) {
+  console.log("Decision is compliant.");
+} else {
+  for (const v of result.policyViolations) {
+    console.log(`VIOLATION — ${v.rule}`);
+    console.log(`  proof:      ${v.proofId}`);
+    console.log(`  confidence: ${v.confidenceLevel} (required: ${v.threshold})`);
+    console.log(`  class:      ${v.reversibilityClass}`);
+  }
+}
+```
+
+`getPolicyCheck()` is a lightweight yes/no compliance check. It returns `result.policyCompliant` (boolean) and `result.policyViolations` (array). For the full audit trail including timestamps and intermediate confidence checkpoints, use `getConfidenceTrail()` instead.
+
+---
+
+## Timing Breakdown
+
+Anchor the full decision chronology on-chain alongside the confidence anchor. Three ISO8601 timestamps mark **when the instruction arrived**, **when reasoning began**, and **when the action fired**. A `jurisdictionType` field records who was accountable for the decision.
+
+```typescript
+import { XProofClient, hashString, JURISDICTION_TYPES } from "@xproof/xproof";
+import type { TimingBreakdown } from "@xproof/xproof";
+
+const client = new XProofClient({ apiKey: "pm_your_key" });
+
+const instructionReceivedAt = new Date().toISOString();
+// ... agent reasons ...
+const reasoningStartedAt = new Date().toISOString();
+// ... reasoning completes, agent executes ...
+const actionTakenAt = new Date().toISOString();
+
+const timing: TimingBreakdown = {
+  instructionReceivedAt,
+  reasoningStartedAt,
+  actionTakenAt,
+  jurisdictionType: "autonomous_inference", // agent reached its own conclusion
+};
+
+const cert = await client.certifyWithConfidence(
+  hashString(JSON.stringify({ action: "approve_transfer", amount: 50_000 })),
+  "transfer-decision.json",
+  "treasury-agent",
+  {
+    confidenceLevel: 0.97,
+    thresholdStage: "final",
+    decisionId: "transfer-xyz-2026",
+    reversibilityClass: "irreversible",
+    timing,
+  }
+);
+
+// cert.timingBreakdown is populated in the API response:
+console.log(cert.timingBreakdown?.reasoningDurationMs); // ms between reasoning_started_at and action_taken_at
+console.log(cert.timingBreakdown?.totalDurationMs);     // ms between instruction_received_at and action_taken_at
+```
+
+### `jurisdictionType` values
+
+| Value | Meaning | Who bears accountability |
+|---|---|---|
+| `"instruction_following"` | Agent executed an explicit human instruction | Principal (human) |
+| `"autonomous_inference"` | Agent reached its own conclusion | Agent and its operator |
+| `"human_approved"` | Agent recommended, human approved before action | Shared |
+
+All valid values are exported as the `JURISDICTION_TYPES` constant for runtime validation:
+
+```typescript
+import { JURISDICTION_TYPES } from "@xproof/xproof";
+
+// ["instruction_following", "autonomous_inference", "human_approved"]
+console.log(JURISDICTION_TYPES);
+
+// Runtime guard
+function isValidJurisdiction(s: string): boolean {
+  return (JURISDICTION_TYPES as readonly string[]).includes(s);
+}
+```
+
+### Reading timing data back
+
+```typescript
+const cert = await client.verify("certification-uuid");
+
+if (cert.timingBreakdown) {
+  const { instructionReceivedAt, reasoningDurationMs, totalDurationMs } = cert.timingBreakdown;
+  console.log(`Instruction at: ${instructionReceivedAt}`);
+  console.log(`Reasoning took: ${reasoningDurationMs}ms`);
+  console.log(`Total latency:  ${totalDurationMs}ms`);
+}
+```
+
+> All four fields (`instructionReceivedAt`, `reasoningStartedAt`, `actionTakenAt`, `jurisdictionType`) are optional — you can anchor whichever timestamps are available. `reasoningDurationMs` and `totalDurationMs` are computed server-side and appear only in responses, never in requests.
+
+---
+
+## Governance & Policy Enforcement
+
+xProof detects automatically when an agent acted with insufficient confidence on an irreversible action — and writes the evidence on-chain before you ever open an incident report.
+
+### Mark decisions as reversible, costly, or irreversible
+
+Add `reversibilityClass` to any certified action. The server enforces a policy: **irreversible actions require `confidenceLevel >= 0.95`**. Anything below that threshold generates a policy violation anchored to the chain.
+
+```typescript
+import { XProofClient, hashString } from "@xproof/xproof";
+
+const client = new XProofClient({ apiKey: "pm_..." });
+
+// An agent is about to execute a trade it cannot undo.
+// It certifies its reasoning at 0.72 confidence — below the 0.95 threshold.
+const cert = await client.certifyWithConfidence(
+  hashString(JSON.stringify({ action: "sell", ticker: "AAPL", qty: 500 })),
+  "trade-decision.json",
+  "trading-agent",
+  {
+    confidenceLevel: 0.72,              // Agent's self-assessed confidence
+    thresholdStage: "pre-commitment",
+    decisionId: "trade-xyz-2026",
+    reversibilityClass: "irreversible", // This action cannot be undone
+  }
+);
+
+// cert.reversibilityClass === "irreversible"
+// The server has recorded a policy violation: 0.72 < 0.95 required
+```
+
+### Check compliance — without fetching the full trail
+
+```typescript
+import type { PolicyCheckResult } from "@xproof/xproof";
+
+const check: PolicyCheckResult = await client.getPolicyCheck("trade-xyz-2026");
+
+if (!check.policyCompliant) {
+  for (const v of check.policyViolations) {
+    console.log(`VIOLATION — ${v.rule}`);
+    console.log(`  proof:      ${v.proofId}`);
+    console.log(`  confidence: ${v.confidenceLevel} (required: ${v.threshold})`);
+    console.log(`  class:      ${v.reversibilityClass}`);
+    // → VIOLATION — irreversible actions require confidence_level >= 0.95
+    // →   proof:      abc-uuid
+    // →   confidence: 0.72 (required: 0.95)
+    // →   class:      irreversible
+  }
+}
+```
+
+### Full confidence trail with policy result
+
+```typescript
+const trail = await client.getConfidenceTrail("trade-xyz-2026");
+
+console.log(trail.policyCompliant);        // false
+console.log(trail.policyViolations.length); // 1
+console.log(trail.currentConfidence);       // 0.72
+console.log(trail.isFinalized);             // false — decision still open
+```
+
+### Observability — surfacing violations in dashboards
+
+Throwing an error is enough to halt execution, but it gives your observability
+stack nothing structured to alert on.  The pattern below emits a
+machine-readable JSON log line for each violation and optionally fires a
+webhook, so Datadog / Grafana / CloudWatch log-based alerts can pick up
+violations without grepping free-form text.
+
+```typescript
+import { XProofClient } from "@xproof/xproof";
+import type { PolicyViolation } from "@xproof/xproof";
+
+const client = new XProofClient({ apiKey: "pm_..." });
+const decisionId = "trade-xyz-2026"; // the decision ID passed to certifyWithConfidence()
+
+// Optional: set a webhook URL to receive violation payloads
+const VIOLATION_WEBHOOK_URL: string | null = null; // e.g. "https://hooks.example.com/compliance"
+
+async function emitViolation(decisionId: string, violation: PolicyViolation): Promise<void> {
+  const payload = {
+    event:               "policy_violation",
+    decision_id:         decisionId,
+    rule:                violation.rule,
+    proof_id:            violation.proofId,
+    confidence_level:    violation.confidenceLevel,
+    threshold:           violation.threshold,
+    reversibility_class: violation.reversibilityClass,
+    threshold_stage:     violation.thresholdStage,
+  };
+
+  // ── Structured JSON log (ingested by Datadog / CloudWatch / Loki) ─────────
+  // console.error writes to stderr, which log shippers (Fluentd, the Datadog
+  // Agent, the CloudWatch agent) forward verbatim.
+  // Drop-in replacements: pino.error(payload) emits NDJSON with no extra
+  // config; for winston, configure a JSON transport first (e.g.
+  // `winston.createLogger({ format: winston.format.json(), ... })`), then
+  // call logger.error(payload) to get the same single-line JSON output.
+  console.error(JSON.stringify(payload));
+
+  // ── Optional webhook / alerting callback (best-effort) ───────────────────
+  if (VIOLATION_WEBHOOK_URL) {
+    try {
+      await fetch(VIOLATION_WEBHOOK_URL, {
+        method:  "POST",
+        headers: { "Content-Type": "application/json" },
+        body:    JSON.stringify(payload),
+        signal:  AbortSignal.timeout(5000), // fire-and-forget; add retry logic as needed
+      });
+    } catch (exc) {
+      // Best-effort delivery — a webhook failure must NOT swallow the
+      // compliance violation itself.  Log and continue to the throw below.
+      console.warn(JSON.stringify({ event: "webhook_error", detail: String(exc) }));
+    }
+  }
+}
+
+const check = await client.getPolicyCheck(decisionId);
+
+if (!check.policyCompliant) {
+  for (const v of check.policyViolations) {
+    await emitViolation(decisionId, v);
+  }
+
+  // ── Full audit trail for post-mortem / SIEM export ────────────────────────
+  // getConfidenceTrail() returns a ConfidenceTrail object containing every
+  // certification event — confidence levels, timestamps, transaction hashes —
+  // so you can attach the complete chain-of-evidence to an incident ticket or
+  // ship it to your SIEM without a separate lookup.
+  // Note: redact sensitive fields from trail.stages before logging or
+  // exporting to centralised logs / SIEM in production environments.
+  const trail = await client.getConfidenceTrail(decisionId);
+  console.error(JSON.stringify({
+    event:              "audit_trail",
+    decision_id:        decisionId,
+    current_confidence: trail.currentConfidence,
+    is_finalized:       trail.isFinalized,
+    total_anchors:      trail.totalAnchors,
+    stages:             trail.stages,
+  }));
+
+  throw new Error("Action aborted: policy compliance check failed.");
+}
+```
+
+Each `console.error(JSON.stringify(...))` call writes a single-line JSON object
+that log shippers (Fluentd, the Datadog Agent, the CloudWatch agent) forward
+verbatim.  Create a log-based metric or alert on `event = "policy_violation"` to
+get dashboard counts and threshold alerts with no extra instrumentation.
+
+#### Drop-in: pino
+
+Replace `console.error(JSON.stringify(payload))` with a single `pino` call — no extra config needed, pino emits NDJSON by default:
+
+```typescript
+import pino from "pino";
+
+const logger = pino();
+
+// inside emitViolation():
+logger.error(payload); // emits: {"level":50,"time":...,"rule":"...","event":"policy_violation",...}
+```
+
+#### Drop-in: winston
+
+Configure a JSON transport once, then call `logger.error(payload)` to get the same single-line JSON output:
+
+```typescript
+import winston from "winston";
+
+const logger = winston.createLogger({
+  level: "error",
+  format: winston.format.json(),
+  transports: [new winston.transports.Console({ stderrLevels: ["error"] })],
+});
+
+// inside emitViolation():
+logger.error("policy_violation", payload);
+```
+
+Both emit a single JSON line per violation — identical in structure to the `console.error` version above.
+
+> **Runnable example** — `examples/observability.ts` in this repo demonstrates the full pattern (violation detection, structured logging, webhook delivery, audit trail) with a mock client. Run it with `npx tsx examples/observability.ts`.
+
+### Three classes, one parameter
+
+| `reversibilityClass` | What it means | Policy threshold |
+|---|---|---|
+| `"reversible"` | Action can be undone (e.g. draft, preview) | None — any confidence accepted |
+| `"costly"` | Undoable but expensive (e.g. API call, DB write) | None — any confidence accepted |
+| `"irreversible"` | Cannot be undone (e.g. trade, deletion, send) | `confidenceLevel >= 0.95` required |
+
+> The threshold is configured server-side (`IRREVERSIBLE_CONFIDENCE_THRESHOLD=0.95`). All violations are written on-chain and cannot be amended.
+
+---
+
 ## Pricing
 
 ```typescript
@@ -208,11 +516,18 @@ try {
 | `XProofClient.register(agentName)` | Register agent, get trial key |
 | `certify(path, author, fileName?, fourW?)` | Certify file (hashes locally) |
 | `certifyHash(hash, name, author, fourW?)` | Certify by pre-computed hash |
+| `certifyWithConfidence(hash, name, author, opts)` | Certify with confidence + governance class |
 | `batchCertify(files)` | Batch certify (up to 50) |
 | `verify(proofId)` | Look up by proof ID |
 | `verifyHash(fileHash)` | Look up by file hash |
+| `getConfidenceTrail(decisionId)` | Full trail with `policyCompliant` + violations |
+| `getPolicyCheck(decisionId)` | Lightweight compliance check — no full trail |
 | `getPricing()` | Get current pricing |
 
+## Contributing
+
+If you use VS Code, install the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) (`dbaeumer.vscode-eslint`). The repo includes `.vscode/settings.json` that configures ESLint as the default formatter and runs `eslint --fix`, organise-imports, and remove-unused-imports automatically on every save. VS Code will prompt you to install the recommended extension when you open the folder.
+
 ## Links
 
 - [xproof.app](https://xproof.app) — dashboard & docs

package/dist/{client-CWrki-T_.d.mts → client-Dq5Be9On.d.mts}

@@ -1,3 +1,37 @@
+type JurisdictionType = "instruction_following" | "autonomous_inference" | "human_approved";
+/**
+ * All valid `JurisdictionType` values — useful for runtime validation.
+ *
+ * - `instruction_following` — agent executed an explicit human instruction;
+ *   accountability follows the principal.
+ * - `autonomous_inference` — agent reached its own conclusion; agent and its
+ *   operator bear primary accountability.
+ * - `human_approved` — agent recommended, human approved; shared accountability.
+ */
+declare const JURISDICTION_TYPES: readonly JurisdictionType[];
+/**
+ * Decomposed decision timeline for forensic audit.
+ *
+ * Pass a `TimingBreakdown` to `certifyWithConfidence()` via `confidence.timing`
+ * to anchor the full decision chronology on-chain.
+ *
+ * All timestamp fields are optional ISO8601 strings with a timezone offset
+ * (e.g. `"2026-04-20T14:31:58Z"`).
+ *
+ * When read back from the API the server populates two computed fields:
+ * - `reasoningDurationMs` — ms between `reasoningStartedAt` and `actionTakenAt`
+ * - `totalDurationMs` — ms between `instructionReceivedAt` and `actionTakenAt`
+ */
+interface TimingBreakdown {
+    instructionReceivedAt?: string;
+    reasoningStartedAt?: string;
+    actionTakenAt?: string;
+    jurisdictionType?: JurisdictionType;
+    /** Computed by server; present in API responses only. */
+    reasoningDurationMs?: number;
+    /** Computed by server; present in API responses only. */
+    totalDurationMs?: number;
+}
 interface Certification {
     id: string;
     fileName: string;
@@ -10,6 +44,7 @@ interface Certification {
     isPublic: boolean;
     certificateUrl: string;
     verifyUrl: string;
+    timingBreakdown?: TimingBreakdown;
 }
 interface BatchResultSummary {
     total: number;
@@ -68,6 +103,8 @@ interface ConfidenceOptions {
     thresholdStage: ThresholdStage;
     decisionId: string;
     reversibilityClass?: ReversibilityClass;
+    /** Optional timing breakdown to anchor the full decision chronology on-chain. */
+    timing?: TimingBreakdown;
 }
 interface ConfidenceTrailStage {
     proofId: string;
@@ -125,6 +162,7 @@ interface BatchFileEntry {
     fileName?: string;
     author?: string;
     metadata?: Record<string, unknown>;
+    timing?: TimingBreakdown;
 }
 interface XProofClientOptions {
     apiKey?: string;
@@ -189,4 +227,4 @@ declare class XProofClient {
     private handleError;
 }
 
-export { type BatchFileEntry as B, type Certification as C, type ExecutionContext as E, type FourWOptions as F, type PolicyCheckResult as P, type RegistrationResult as R, type ThresholdStage as T, XProofClient as X, type BatchResult as a, type BatchResultSummary as b, type CertifyHashOptions as c, type ConfidenceOptions as d, type ConfidenceTrail as e, type ConfidenceTrailDrift as f, type ConfidenceTrailStage as g, type ContextDrift as h, type ContextDriftStage as i, type PolicyViolation as j, type PricingInfo as k, type PricingTier as l, type ReversibilityClass as m, type TrialInfo as n, type XProofClientOptions as o };
+export { type BatchFileEntry as B, type Certification as C, type ExecutionContext as E, type FourWOptions as F, JURISDICTION_TYPES as J, type PolicyCheckResult as P, type RegistrationResult as R, type ThresholdStage as T, XProofClient as X, type BatchResult as a, type BatchResultSummary as b, type CertifyHashOptions as c, type ConfidenceOptions as d, type ConfidenceTrail as e, type ConfidenceTrailDrift as f, type ConfidenceTrailStage as g, type ContextDrift as h, type ContextDriftStage as i, type JurisdictionType as j, type PolicyViolation as k, type PricingInfo as l, type PricingTier as m, type ReversibilityClass as n, type TimingBreakdown as o, type TrialInfo as p, type XProofClientOptions as q };

package/dist/{client-CWrki-T_.d.ts → client-Dq5Be9On.d.ts}

@@ -1,3 +1,37 @@
+type JurisdictionType = "instruction_following" | "autonomous_inference" | "human_approved";
+/**
+ * All valid `JurisdictionType` values — useful for runtime validation.
+ *
+ * - `instruction_following` — agent executed an explicit human instruction;
+ *   accountability follows the principal.
+ * - `autonomous_inference` — agent reached its own conclusion; agent and its
+ *   operator bear primary accountability.
+ * - `human_approved` — agent recommended, human approved; shared accountability.
+ */
+declare const JURISDICTION_TYPES: readonly JurisdictionType[];
+/**
+ * Decomposed decision timeline for forensic audit.
+ *
+ * Pass a `TimingBreakdown` to `certifyWithConfidence()` via `confidence.timing`
+ * to anchor the full decision chronology on-chain.
+ *
+ * All timestamp fields are optional ISO8601 strings with a timezone offset
+ * (e.g. `"2026-04-20T14:31:58Z"`).
+ *
+ * When read back from the API the server populates two computed fields:
+ * - `reasoningDurationMs` — ms between `reasoningStartedAt` and `actionTakenAt`
+ * - `totalDurationMs` — ms between `instructionReceivedAt` and `actionTakenAt`
+ */
+interface TimingBreakdown {
+    instructionReceivedAt?: string;
+    reasoningStartedAt?: string;
+    actionTakenAt?: string;
+    jurisdictionType?: JurisdictionType;
+    /** Computed by server; present in API responses only. */
+    reasoningDurationMs?: number;
+    /** Computed by server; present in API responses only. */
+    totalDurationMs?: number;
+}
 interface Certification {
     id: string;
     fileName: string;
@@ -10,6 +44,7 @@ interface Certification {
     isPublic: boolean;
     certificateUrl: string;
     verifyUrl: string;
+    timingBreakdown?: TimingBreakdown;
 }
 interface BatchResultSummary {
     total: number;
@@ -68,6 +103,8 @@ interface ConfidenceOptions {
     thresholdStage: ThresholdStage;
     decisionId: string;
     reversibilityClass?: ReversibilityClass;
+    /** Optional timing breakdown to anchor the full decision chronology on-chain. */
+    timing?: TimingBreakdown;
 }
 interface ConfidenceTrailStage {
     proofId: string;
@@ -125,6 +162,7 @@ interface BatchFileEntry {
     fileName?: string;
     author?: string;
     metadata?: Record<string, unknown>;
+    timing?: TimingBreakdown;
 }
 interface XProofClientOptions {
     apiKey?: string;
@@ -189,4 +227,4 @@ declare class XProofClient {
     private handleError;
 }
 
-export { type BatchFileEntry as B, type Certification as C, type ExecutionContext as E, type FourWOptions as F, type PolicyCheckResult as P, type RegistrationResult as R, type ThresholdStage as T, XProofClient as X, type BatchResult as a, type BatchResultSummary as b, type CertifyHashOptions as c, type ConfidenceOptions as d, type ConfidenceTrail as e, type ConfidenceTrailDrift as f, type ConfidenceTrailStage as g, type ContextDrift as h, type ContextDriftStage as i, type PolicyViolation as j, type PricingInfo as k, type PricingTier as l, type ReversibilityClass as m, type TrialInfo as n, type XProofClientOptions as o };
+export { type BatchFileEntry as B, type Certification as C, type ExecutionContext as E, type FourWOptions as F, JURISDICTION_TYPES as J, type PolicyCheckResult as P, type RegistrationResult as R, type ThresholdStage as T, XProofClient as X, type BatchResult as a, type BatchResultSummary as b, type CertifyHashOptions as c, type ConfidenceOptions as d, type ConfidenceTrail as e, type ConfidenceTrailDrift as f, type ConfidenceTrailStage as g, type ContextDrift as h, type ContextDriftStage as i, type JurisdictionType as j, type PolicyViolation as k, type PricingInfo as l, type PricingTier as m, type ReversibilityClass as n, type TimingBreakdown as o, type TrialInfo as p, type XProofClientOptions as q };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-export { B as BatchFileEntry, a as BatchResult, b as BatchResultSummary, C as Certification, c as CertifyHashOptions, d as ConfidenceOptions, e as ConfidenceTrail, f as ConfidenceTrailDrift, g as ConfidenceTrailStage, h as ContextDrift, i as ContextDriftStage, E as ExecutionContext, F as FourWOptions, P as PolicyCheckResult, j as PolicyViolation, k as PricingInfo, l as PricingTier, R as RegistrationResult, m as ReversibilityClass, T as ThresholdStage, n as TrialInfo, X as XProofClient, o as XProofClientOptions } from './client-CWrki-T_.mjs';
+export { B as BatchFileEntry, a as BatchResult, b as BatchResultSummary, C as Certification, c as CertifyHashOptions, d as ConfidenceOptions, e as ConfidenceTrail, f as ConfidenceTrailDrift, g as ConfidenceTrailStage, h as ContextDrift, i as ContextDriftStage, E as ExecutionContext, F as FourWOptions, J as JURISDICTION_TYPES, j as JurisdictionType, P as PolicyCheckResult, k as PolicyViolation, l as PricingInfo, m as PricingTier, R as RegistrationResult, n as ReversibilityClass, T as ThresholdStage, o as TimingBreakdown, p as TrialInfo, X as XProofClient, q as XProofClientOptions } from './client-Dq5Be9On.mjs';
 
 declare class XProofError extends Error {
     statusCode: number;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { B as BatchFileEntry, a as BatchResult, b as BatchResultSummary, C as Certification, c as CertifyHashOptions, d as ConfidenceOptions, e as ConfidenceTrail, f as ConfidenceTrailDrift, g as ConfidenceTrailStage, h as ContextDrift, i as ContextDriftStage, E as ExecutionContext, F as FourWOptions, P as PolicyCheckResult, j as PolicyViolation, k as PricingInfo, l as PricingTier, R as RegistrationResult, m as ReversibilityClass, T as ThresholdStage, n as TrialInfo, X as XProofClient, o as XProofClientOptions } from './client-CWrki-T_.js';
+export { B as BatchFileEntry, a as BatchResult, b as BatchResultSummary, C as Certification, c as CertifyHashOptions, d as ConfidenceOptions, e as ConfidenceTrail, f as ConfidenceTrailDrift, g as ConfidenceTrailStage, h as ContextDrift, i as ContextDriftStage, E as ExecutionContext, F as FourWOptions, J as JURISDICTION_TYPES, j as JurisdictionType, P as PolicyCheckResult, k as PolicyViolation, l as PricingInfo, m as PricingTier, R as RegistrationResult, n as ReversibilityClass, T as ThresholdStage, o as TimingBreakdown, p as TrialInfo, X as XProofClient, q as XProofClientOptions } from './client-Dq5Be9On.js';
 
 declare class XProofError extends Error {
     statusCode: number;

package/dist/index.js

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
   ConflictError: () => ConflictError,
+  JURISDICTION_TYPES: () => JURISDICTION_TYPES,
   NotFoundError: () => NotFoundError,
   RateLimitError: () => RateLimitError,
   ServerError: () => ServerError,
@@ -99,8 +100,47 @@ function hashString(data) {
 }
 
 // src/parse.ts
+function parseTimingBreakdown(raw) {
+  const tb = {};
+  let hasAnyField = false;
+  if (raw.instruction_received_at != null) {
+    tb.instructionReceivedAt = raw.instruction_received_at;
+    hasAnyField = true;
+  }
+  if (raw.reasoning_started_at != null) {
+    tb.reasoningStartedAt = raw.reasoning_started_at;
+    hasAnyField = true;
+  }
+  if (raw.action_taken_at != null) {
+    tb.actionTakenAt = raw.action_taken_at;
+    hasAnyField = true;
+  }
+  if (raw.jurisdiction_type != null) {
+    tb.jurisdictionType = raw.jurisdiction_type;
+    hasAnyField = true;
+  }
+  if (raw.reasoning_duration_ms != null) {
+    tb.reasoningDurationMs = raw.reasoning_duration_ms;
+    hasAnyField = true;
+  }
+  if (raw.total_duration_ms != null) {
+    tb.totalDurationMs = raw.total_duration_ms;
+    hasAnyField = true;
+  }
+  return hasAnyField ? tb : void 0;
+}
 function parseCertification(data) {
   const blockchain = data.blockchain || {};
+  const _meta = data.metadata;
+  const _TIMING_KEYS = [
+    "instruction_received_at",
+    "reasoning_started_at",
+    "action_taken_at",
+    "jurisdiction_type",
+    "reasoning_duration_ms",
+    "total_duration_ms"
+  ];
+  const rawTiming = data.timing_breakdown ?? _meta?.timing_breakdown ?? (_meta && _TIMING_KEYS.some((k) => _meta[k] != null) ? _meta : void 0);
   return {
     id: data.id || data.proof_id || "",
     fileName: data.fileName || data.filename || data.file_name || "",
@@ -112,7 +152,8 @@ function parseCertification(data) {
     blockchainStatus: data.blockchainStatus || data.status || "",
     isPublic: data.isPublic !== void 0 ? !!data.isPublic : data.is_public !== void 0 ? !!data.is_public : true,
     certificateUrl: data.certificateUrl || data.certificate_url || "",
-    verifyUrl: data.verifyUrl || data.verify_url || ""
+    verifyUrl: data.verifyUrl || data.verify_url || "",
+    timingBreakdown: rawTiming ? parseTimingBreakdown(rawTiming) : void 0
   };
 }
 function parseBatchResult(data) {
@@ -170,8 +211,15 @@ function parseRegistrationResult(data) {
   };
 }
 
+// src/types.ts
+var JURISDICTION_TYPES = [
+  "instruction_following",
+  "autonomous_inference",
+  "human_approved"
+];
+
 // src/client.ts
-var VERSION = "0.1.7";
+var VERSION = "0.1.9";
 var DEFAULT_BASE_URL = "https://xproof.app";
 var DEFAULT_TIMEOUT = 3e4;
 var XProofClient = class _XProofClient {
@@ -231,7 +279,25 @@ var XProofClient = class _XProofClient {
         filename: f.fileName ?? "unknown",
         file_hash: f.fileHash
       };
-      if (f.metadata) entry.metadata = f.metadata;
+      const entryMeta = f.metadata ? { ...f.metadata } : {};
+      if (f.timing !== void 0) {
+        const t = f.timing;
+        if (t.jurisdictionType !== void 0 && !JURISDICTION_TYPES.includes(t.jurisdictionType)) {
+          throw new ValidationError(
+            `timing.jurisdictionType must be one of: ${JURISDICTION_TYPES.join(", ")}`,
+            {}
+          );
+        }
+        if (t.instructionReceivedAt !== void 0)
+          entryMeta.instruction_received_at = t.instructionReceivedAt;
+        if (t.reasoningStartedAt !== void 0)
+          entryMeta.reasoning_started_at = t.reasoningStartedAt;
+        if (t.actionTakenAt !== void 0)
+          entryMeta.action_taken_at = t.actionTakenAt;
+        if (t.jurisdictionType !== void 0)
+          entryMeta.jurisdiction_type = t.jurisdictionType;
+      }
+      if (Object.keys(entryMeta).length > 0) entry.metadata = entryMeta;
       return entry;
     });
     const payload = { files: entries };
@@ -241,13 +307,13 @@ var XProofClient = class _XProofClient {
     return parseBatchResult(data);
   }
   async verify(proofId) {
-    const data = await this.request("GET", `/api/proof/${proofId}`, {
+    const data = await this.request("GET", `/api/proof/${encodeURIComponent(proofId)}`, {
       authRequired: false
     });
     return parseCertification(data);
   }
   async verifyHash(fileHash) {
-    const data = await this.request("GET", `/api/proof/hash/${fileHash}`, {
+    const data = await this.request("GET", `/api/proof/hash/${encodeURIComponent(fileHash)}`, {
       authRequired: false
     });
     return parseCertification(data);
@@ -275,6 +341,23 @@ var XProofClient = class _XProofClient {
     metadata.decision_id = confidence.decisionId;
     if (confidence.reversibilityClass !== void 0)
       metadata.reversibility_class = confidence.reversibilityClass;
+    if (confidence.timing !== void 0) {
+      const t = confidence.timing;
+      if (t.jurisdictionType !== void 0 && !JURISDICTION_TYPES.includes(t.jurisdictionType)) {
+        throw new ValidationError(
+          `timing.jurisdictionType must be one of: ${JURISDICTION_TYPES.join(", ")}`,
+          {}
+        );
+      }
+      if (t.instructionReceivedAt !== void 0)
+        metadata.instruction_received_at = t.instructionReceivedAt;
+      if (t.reasoningStartedAt !== void 0)
+        metadata.reasoning_started_at = t.reasoningStartedAt;
+      if (t.actionTakenAt !== void 0)
+        metadata.action_taken_at = t.actionTakenAt;
+      if (t.jurisdictionType !== void 0)
+        metadata.jurisdiction_type = t.jurisdictionType;
+    }
     const payload = {
       filename: fileName,
       file_hash: fileHash,
@@ -285,6 +368,9 @@ var XProofClient = class _XProofClient {
     return parseCertification(data);
   }
   async getConfidenceTrail(decisionId) {
+    if (!decisionId || !decisionId.trim()) {
+      throw new ValidationError("decisionId is required", {});
+    }
     const data = await this.request(
       "GET",
       `/api/confidence-trail/${encodeURIComponent(decisionId)}`,
@@ -338,6 +424,9 @@ var XProofClient = class _XProofClient {
     };
   }
   async getContextDrift(decisionId) {
+    if (!decisionId || !decisionId.trim()) {
+      throw new ValidationError("decisionId is required", {});
+    }
     const data = await this.request(
       "GET",
       `/api/context-drift/${encodeURIComponent(decisionId)}`,
@@ -491,6 +580,7 @@ var XProofClient = class _XProofClient {
 0 && (module.exports = {
   AuthenticationError,
   ConflictError,
+  JURISDICTION_TYPES,
   NotFoundError,
   RateLimitError,
   ServerError,