Initial scaffold: SvelteKit viewer with parser, verifier, and metrics

- SvelteKit app scaffold with static adapter
- Bundle parser: JSONL trace/receipts + JSON manifests
- Client-side verifier: hash chain continuity, schema validation,
  event-receipt linkage, bundle completeness
- Metrics computation: event types, policy decisions, duration
- Example bundle with 4 trace events and receipts
- TypeScript verifier package stub
- UX documentation with layout and color system

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cmangun

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.1.0] - 2025-02-21
+
+### Added
+- SvelteKit viewer app scaffold
+- Bundle parser (JSONL + JSON)
+- Client-side verifier (hash chain, schema, linkage)
+- Metrics computation
+- Example bundle
+- UX documentation

CONTRIBUTING.md

@@ -0,0 +1,6 @@
+# Contributing
+
+1. Open an issue
+2. Fork and branch
+3. Submit PR with screenshots/GIFs for UI changes
+4. Ensure all verification tests pass

README.md

@@ -0,0 +1,63 @@
+# agentic-evidence-viewer
+
+A drag-drop viewer for **agent traces, receipts, policy decisions, and artifacts**.
+
+This repo lets a reviewer open a bundle and see:
+- Integrity status (PASS/FAIL) with reasons
+- Trace timeline and event details
+- Policy decisions and required gates
+- Artifact manifests and previews (safe types)
+- Summary metrics (cost/latency/errors)
+
+Bundle and receipt standards:
+- [agentic-receipts](https://github.com/cmangun/agentic-receipts)
+
+## Quick Start
+
+```bash
+cd apps/viewer
+npm install
+npm run dev
+```
+
+Then drag-drop a bundle from `examples/bundles/`.
+
+## Architecture
+
+```
+Bundle (dropped) → Parser → Verifier → Renderer
+                              ↓
+                    [schema + chain + signature]
+                              ↓
+                    Integrity Badge (PASS/FAIL)
+```
+
+### Views
+
+| View | Description |
+|------|-------------|
+| **Timeline** | Chronological trace events with expandable details |
+| **Policy** | Allow/deny decisions with rationale and policy hash |
+| **Artifacts** | File explorer with safe previews (text/markdown/JSON) |
+| **Metrics** | Cost, latency, error rates, tool call distribution |
+| **Integrity** | Hash chain verification, signature status |
+
+## Tech Stack
+
+- **SvelteKit** — UI framework
+- **TypeScript** — Type safety
+- **WASM verifier** — Client-side hash chain and signature verification
+
+## Suite
+
+This repo is part of the **Agentic Evidence Suite**:
+- [agentic-receipts](https://github.com/cmangun/agentic-receipts) (standard)
+- [agentic-trace-cli](https://github.com/cmangun/agentic-trace-cli) (tooling)
+- [agentic-artifacts](https://github.com/cmangun/agentic-artifacts) (outputs)
+- [agentic-policy-engine](https://github.com/cmangun/agentic-policy-engine) (governance)
+- [agentic-eval-harness](https://github.com/cmangun/agentic-eval-harness) (scenarios)
+- [agentic-evidence-viewer](https://github.com/cmangun/agentic-evidence-viewer) (review UI)
+
+## License
+
+MIT

SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+Report vulnerabilities in bundle verification or artifact preview rendering responsibly.
+
+## Scope
+
+- Client-side verification bypass
+- XSS via artifact preview
+- Bundle parsing exploits

apps/viewer/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "agentic-evidence-viewer",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-static": "^3.0.0",
+    "@sveltejs/kit": "^2.0.0",
+    "svelte": "^5.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0"
+  }
+}

apps/viewer/src/lib/metrics.ts

@@ -0,0 +1,56 @@
+/**
+ * Metrics computation from parsed bundles.
+ *
+ * Computes summary statistics for display in the metrics panel.
+ */
+
+import type { ParsedBundle, TraceEvent } from './parser';
+
+export interface BundleMetrics {
+  totalEvents: number;
+  eventTypeCounts: Record<string, number>;
+  totalReceipts: number;
+  totalArtifacts: number;
+  policyDecisions: {
+    allow: number;
+    deny: number;
+    require_approval: number;
+  };
+  durationMs: number;
+  hasSignatures: boolean;
+}
+
+/**
+ * Compute metrics from a parsed bundle.
+ */
+export function computeMetrics(bundle: ParsedBundle): BundleMetrics {
+  const eventTypeCounts: Record<string, number> = {};
+  for (const event of bundle.events) {
+    eventTypeCounts[event.event_type] = (eventTypeCounts[event.event_type] || 0) + 1;
+  }
+
+  const policyEvents = bundle.events.filter((e) => e.event_type === 'policy_decision');
+  const policyDecisions = { allow: 0, deny: 0, require_approval: 0 };
+  for (const event of policyEvents) {
+    const decision = (event.payload as Record<string, string>).decision;
+    if (decision in policyDecisions) {
+      policyDecisions[decision as keyof typeof policyDecisions]++;
+    }
+  }
+
+  const timestamps = bundle.events.map((e) => new Date(e.timestamp).getTime());
+  const durationMs =
+    timestamps.length >= 2 ? Math.max(...timestamps) - Math.min(...timestamps) : 0;
+
+  const hasSignatures = bundle.receipts.some((r) => r.signature != null);
+
+  return {
+    totalEvents: bundle.events.length,
+    eventTypeCounts,
+    totalReceipts: bundle.receipts.length,
+    totalArtifacts: bundle.artifacts.length,
+    policyDecisions,
+    durationMs,
+    hasSignatures,
+  };
+}

apps/viewer/src/lib/parser.ts

@@ -0,0 +1,104 @@
+/**
+ * Bundle parser: reads trace JSONL, receipts JSONL, and manifests.
+ *
+ * Parses the contents of an agent evidence bundle into typed structures
+ * for rendering in the viewer.
+ */
+
+export interface TraceEvent {
+  event_id: string;
+  event_type: string;
+  timestamp: string;
+  sequence: number;
+  parent_event_id?: string;
+  payload: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Receipt {
+  receipt_id: string;
+  event_id: string;
+  hash: string;
+  prev_hash: string;
+  timestamp: string;
+  event_type: string;
+  signature?: {
+    algorithm: string;
+    public_key: string;
+    value: string;
+  };
+  metadata?: Record<string, unknown>;
+}
+
+export interface Artifact {
+  artifact_id: string;
+  event_id: string;
+  hash: string;
+  path: string;
+  artifact_type: string;
+  content_type?: string;
+  size_bytes?: number;
+  provenance?: {
+    trace_event_ids: string[];
+    model?: string;
+    tool?: string;
+  };
+}
+
+export interface BundleManifest {
+  bundle_id: string;
+  version: string;
+  created_at: string;
+  trace_file: string;
+  receipts_file: string;
+  artifacts_manifest?: string;
+  event_count: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ParsedBundle {
+  manifest: BundleManifest;
+  events: TraceEvent[];
+  receipts: Receipt[];
+  artifacts: Artifact[];
+}
+
+/**
+ * Parse JSONL content into an array of objects.
+ */
+export function parseJsonl<T>(content: string): T[] {
+  return content
+    .trim()
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line) => JSON.parse(line) as T);
+}
+
+/**
+ * Parse a complete bundle from file contents.
+ */
+export function parseBundle(files: Map<string, string>): ParsedBundle {
+  const manifestContent = files.get('bundle.json') || files.get('manifest.json');
+  if (!manifestContent) {
+    throw new Error('Bundle manifest (bundle.json or manifest.json) not found');
+  }
+
+  const manifest: BundleManifest = JSON.parse(manifestContent);
+
+  const traceContent = files.get(manifest.trace_file) || '';
+  const receiptsContent = files.get(manifest.receipts_file) || '';
+  const artifactsContent = manifest.artifacts_manifest
+    ? files.get(manifest.artifacts_manifest) || ''
+    : '';
+
+  const events = traceContent ? parseJsonl<TraceEvent>(traceContent) : [];
+  const receipts = receiptsContent ? parseJsonl<Receipt>(receiptsContent) : [];
+
+  let artifacts: Artifact[] = [];
+  if (artifactsContent) {
+    const artifactManifest = JSON.parse(artifactsContent);
+    artifacts = artifactManifest.artifacts || [];
+  }
+
+  return { manifest, events, receipts, artifacts };
+}

apps/viewer/src/lib/verifier.ts

@@ -0,0 +1,122 @@
+/**
+ * Client-side verification of hash chains and signatures.
+ *
+ * Verifies bundle integrity without requiring a server:
+ * - Hash chain continuity (each receipt chains to the previous)
+ * - Schema validation (required fields present)
+ * - Signature verification (when available, via WebCrypto or WASM)
+ */
+
+import type { Receipt, ParsedBundle } from './parser';
+
+export interface VerificationResult {
+  passed: boolean;
+  checks: VerificationCheck[];
+  summary: string;
+}
+
+export interface VerificationCheck {
+  name: string;
+  passed: boolean;
+  details: string;
+}
+
+/**
+ * Verify the integrity of a parsed bundle.
+ */
+export function verifyBundle(bundle: ParsedBundle): VerificationResult {
+  const checks: VerificationCheck[] = [];
+
+  // Check 1: Bundle has events and receipts
+  checks.push({
+    name: 'Bundle completeness',
+    passed: bundle.events.length > 0 && bundle.receipts.length > 0,
+    details: `${bundle.events.length} events, ${bundle.receipts.length} receipts`,
+  });
+
+  // Check 2: Event count matches manifest
+  checks.push({
+    name: 'Event count match',
+    passed: bundle.events.length === bundle.manifest.event_count,
+    details: `Manifest declares ${bundle.manifest.event_count}, found ${bundle.events.length}`,
+  });
+
+  // Check 3: Receipt count matches event count
+  checks.push({
+    name: 'Receipt coverage',
+    passed: bundle.receipts.length === bundle.events.length,
+    details: `${bundle.receipts.length} receipts for ${bundle.events.length} events`,
+  });
+
+  // Check 4: Hash chain continuity
+  const chainResult = verifyHashChain(bundle.receipts);
+  checks.push(chainResult);
+
+  // Check 5: Event-receipt linkage
+  const linkageResult = verifyEventReceiptLinkage(bundle);
+  checks.push(linkageResult);
+
+  const passed = checks.every((c) => c.passed);
+  const failedCount = checks.filter((c) => !c.passed).length;
+
+  return {
+    passed,
+    checks,
+    summary: passed
+      ? `All ${checks.length} checks passed`
+      : `${failedCount}/${checks.length} checks failed`,
+  };
+}
+
+/**
+ * Verify hash chain continuity: each receipt's prev_hash matches the
+ * previous receipt's hash.
+ */
+function verifyHashChain(receipts: Receipt[]): VerificationCheck {
+  if (receipts.length === 0) {
+    return { name: 'Hash chain', passed: false, details: 'No receipts to verify' };
+  }
+
+  // First receipt should have prev_hash = "genesis"
+  if (receipts[0].prev_hash !== 'genesis') {
+    return {
+      name: 'Hash chain',
+      passed: false,
+      details: `First receipt prev_hash is "${receipts[0].prev_hash}", expected "genesis"`,
+    };
+  }
+
+  // Each subsequent receipt should chain to the previous
+  for (let i = 1; i < receipts.length; i++) {
+    if (receipts[i].prev_hash !== receipts[i - 1].hash) {
+      return {
+        name: 'Hash chain',
+        passed: false,
+        details: `Chain broken at receipt ${i}: prev_hash doesn't match previous hash`,
+      };
+    }
+  }
+
+  return {
+    name: 'Hash chain',
+    passed: true,
+    details: `${receipts.length} receipts form a continuous chain`,
+  };
+}
+
+/**
+ * Verify that every event has a corresponding receipt.
+ */
+function verifyEventReceiptLinkage(bundle: ParsedBundle): VerificationCheck {
+  const receiptEventIds = new Set(bundle.receipts.map((r) => r.event_id));
+  const unlinked = bundle.events.filter((e) => !receiptEventIds.has(e.event_id));
+
+  return {
+    name: 'Event-receipt linkage',
+    passed: unlinked.length === 0,
+    details:
+      unlinked.length === 0
+        ? 'All events have corresponding receipts'
+        : `${unlinked.length} events missing receipts`,
+  };
+}