@fluxpointstudios/orynq-sdk-flight-recorder 0.1.0

package/src/integration/openclaw-adapter.ts

@@ -0,0 +1,206 @@
+/**
+ * Adapter for migrating from poi-openclaw to flight-recorder.
+ * Bridges legacy trace formats to the new ManifestV2 format.
+ */
+
+import type {
+  RecorderConfig,
+  RecordingResult,
+  ManifestV2,
+  InferenceStartEvent,
+  InferenceEndEvent,
+  ToolCallEvent,
+  ToolResultEvent,
+} from "../types.js";
+import { FlightRecorder } from "../recorder/stream-recorder.js";
+import { sha256String } from "../crypto/hashing.js";
+
+/**
+ * Partial event types without seq and ts (added by recorder).
+ */
+type PartialInferenceStart = Omit<InferenceStartEvent, "seq" | "ts">;
+type PartialInferenceEnd = Omit<InferenceEndEvent, "seq" | "ts">;
+type PartialToolCall = Omit<ToolCallEvent, "seq" | "ts">;
+type PartialToolResult = Omit<ToolResultEvent, "seq" | "ts">;
+type PartialRecorderEvent = PartialInferenceStart | PartialInferenceEnd | PartialToolCall | PartialToolResult;
+
+/**
+ * Legacy trace event format from poi-openclaw.
+ */
+export interface LegacyTraceEvent {
+  ts: string;
+  kind: "user" | "assistant" | "tool_call" | "tool_result";
+  agentId?: string;
+  sessionId?: string;
+  contentHash: string;
+  content?: string | null;
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Legacy trace bundle from poi-openclaw.
+ */
+export interface LegacyTraceBundle {
+  bundleId: string;
+  events: LegacyTraceEvent[];
+}
+
+/**
+ * Legacy manifest format from poi-openclaw.
+ */
+export interface LegacyManifest {
+  formatVersion: string;
+  agentId: string;
+  rootHash: string;
+  manifestHash: string;
+  merkleRoot: string;
+  totalEvents: number;
+  totalSpans: number;
+  createdAt: string;
+  metadata?: { bundlePath?: string };
+}
+
+/**
+ * Adapter to bridge poi-openclaw traces to flight-recorder.
+ */
+export class OpenClawAdapter {
+  constructor(private readonly config: RecorderConfig) {}
+
+  /**
+   * Convert a legacy trace bundle to a new recording.
+   */
+  async importLegacyBundle(bundle: LegacyTraceBundle): Promise<RecordingResult> {
+    const recorder = new FlightRecorder({
+      ...this.config,
+      sessionId: bundle.bundleId,
+    });
+
+    await recorder.start();
+
+    for (const event of bundle.events) {
+      const converted = await this.convertEvent(event);
+      if (converted) {
+        await recorder.record(converted);
+      }
+    }
+
+    return recorder.finalize();
+  }
+
+  /**
+   * Convert a legacy event to a RecorderEvent.
+   */
+  private convertEvent(event: LegacyTraceEvent): PartialRecorderEvent | null {
+    switch (event.kind) {
+      case "user": {
+        const result: PartialInferenceStart = {
+          kind: "inference:start",
+          requestId: `req-${Date.now()}`,
+          model: "unknown",
+          promptHash: event.contentHash,
+          params: {},
+        };
+        if (event.sessionId) result.spanId = event.sessionId;
+        return result;
+      }
+
+      case "assistant": {
+        const result: PartialInferenceEnd = {
+          kind: "inference:end",
+          requestId: `req-${Date.now()}`,
+          outputHash: event.contentHash,
+          tokenCounts: { prompt: 0, completion: 0 },
+          durationMs: 0,
+        };
+        if (event.sessionId) result.spanId = event.sessionId;
+        return result;
+      }
+
+      case "tool_call": {
+        const result: PartialToolCall = {
+          kind: "tool:call",
+          toolName: (event.meta?.toolName as string) || "unknown",
+          argsHash: event.contentHash,
+          visibility: "private",
+        };
+        if (event.sessionId) result.spanId = event.sessionId;
+        return result;
+      }
+
+      case "tool_result": {
+        const result: PartialToolResult = {
+          kind: "tool:result",
+          toolName: (event.meta?.toolName as string) || "unknown",
+          resultHash: event.contentHash,
+          success: true,
+          visibility: "private",
+        };
+        if (event.sessionId) result.spanId = event.sessionId;
+        return result;
+      }
+
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Convert a legacy manifest to ManifestV2 format.
+   */
+  async convertManifest(legacy: LegacyManifest): Promise<ManifestV2> {
+    const now = new Date().toISOString();
+
+    return {
+      formatVersion: "2.0",
+      agentId: legacy.agentId,
+      sessionId: legacy.metadata?.bundlePath || `migrated-${Date.now()}`,
+
+      rootHash: legacy.rootHash,
+      merkleRoot: legacy.merkleRoot,
+      manifestHash: await sha256String(JSON.stringify(legacy)),
+
+      inputs: {
+        promptHash: "", // Not available in legacy format
+      },
+
+      params: {
+        model: "unknown",
+      },
+
+      runtime: {
+        recorderVersion: "migrated-from-openclaw",
+      },
+
+      chunks: [], // Legacy format doesn't have chunks
+
+      outputs: {
+        transcriptRollingHash: legacy.rootHash,
+        toolCallCount: 0,
+        totalTokens: 0,
+        completionTokens: 0,
+      },
+
+      createdAt: legacy.createdAt,
+      startedAt: legacy.createdAt,
+      endedAt: now,
+      durationMs: 0,
+
+      totalEvents: legacy.totalEvents,
+      totalSpans: legacy.totalSpans,
+    };
+  }
+
+  /**
+   * Check if a manifest is in legacy format.
+   */
+  static isLegacyManifest(manifest: unknown): manifest is LegacyManifest {
+    if (!manifest || typeof manifest !== "object") return false;
+    const m = manifest as Record<string, unknown>;
+    return (
+      typeof m.formatVersion === "string" &&
+      m.formatVersion.startsWith("1.") &&
+      typeof m.agentId === "string" &&
+      typeof m.rootHash === "string"
+    );
+  }
+}

package/src/manifest/index.ts

@@ -0,0 +1 @@
+export { ManifestBuilder } from "./manifest-builder.js";

package/src/manifest/manifest-builder.ts

@@ -0,0 +1,152 @@
+/**
+ * Manifest builder for flight recorder.
+ * Constructs ManifestV2 from recording data.
+ */
+
+import type { ManifestV2, ChunkRef, VerifierPolicy, TeeType } from "../types.js";
+import { sha256Json } from "../crypto/hashing.js";
+
+export interface ManifestInput {
+  agentId: string;
+  sessionId: string;
+  rootHash: string;
+  merkleRoot: string;
+  chunks: ChunkRef[];
+
+  inputs: {
+    promptHash: string;
+    systemPromptHash?: string;
+    toolContextHash?: string;
+  };
+
+  params: {
+    model: string;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    maxTokens?: number;
+  };
+
+  runtime: {
+    recorderVersion: string;
+    nodeVersion?: string;
+    containerDigest?: string;
+    gitCommit?: string;
+  };
+
+  outputs: {
+    transcriptRollingHash: string;
+    toolCallCount: number;
+    totalTokens: number;
+    completionTokens: number;
+  };
+
+  timing: {
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+  };
+
+  stats: {
+    totalEvents: number;
+    totalSpans: number;
+  };
+
+  attestation?: {
+    teeType: TeeType;
+    evidenceHash: string;
+    evidenceUri?: string;
+    verifierPolicy: VerifierPolicy;
+    boundHash: "rootHash" | "manifestHash" | "merkleRoot";
+  };
+}
+
+export class ManifestBuilder {
+  /**
+   * Build a ManifestV2 from input data.
+   */
+  async build(input: ManifestInput): Promise<ManifestV2> {
+    const manifest: ManifestV2 = {
+      formatVersion: "2.0",
+
+      agentId: input.agentId,
+      sessionId: input.sessionId,
+
+      rootHash: input.rootHash,
+      merkleRoot: input.merkleRoot,
+      manifestHash: "", // Computed below
+
+      inputs: input.inputs,
+      params: input.params,
+      runtime: input.runtime,
+      chunks: input.chunks,
+      outputs: input.outputs,
+
+      createdAt: new Date().toISOString(),
+      startedAt: input.timing.startedAt,
+      endedAt: input.timing.endedAt,
+      durationMs: input.timing.durationMs,
+
+      totalEvents: input.stats.totalEvents,
+      totalSpans: input.stats.totalSpans,
+    };
+
+    // Add attestation if provided
+    if (input.attestation) {
+      manifest.attestation = input.attestation;
+    }
+
+    // Compute manifest hash
+    manifest.manifestHash = await this.computeManifestHash(manifest);
+
+    return manifest;
+  }
+
+  /**
+   * Compute the manifest hash.
+   * Hash is computed over the manifest with manifestHash set to empty string.
+   */
+  async computeManifestHash(manifest: ManifestV2): Promise<string> {
+    const toHash = { ...manifest, manifestHash: "" };
+    return sha256Json(toHash, "manifest");
+  }
+
+  /**
+   * Verify a manifest's integrity.
+   */
+  async verify(manifest: ManifestV2): Promise<boolean> {
+    const expectedHash = await this.computeManifestHash(manifest);
+    return manifest.manifestHash === expectedHash;
+  }
+
+  /**
+   * Create a minimal manifest for testing.
+   */
+  static createMinimal(agentId: string, sessionId: string): ManifestV2 {
+    const now = new Date().toISOString();
+    return {
+      formatVersion: "2.0",
+      agentId,
+      sessionId,
+      rootHash: "",
+      merkleRoot: "",
+      manifestHash: "",
+      inputs: { promptHash: "" },
+      params: { model: "unknown" },
+      runtime: { recorderVersion: "0.1.0" },
+      chunks: [],
+      outputs: {
+        transcriptRollingHash: "",
+        toolCallCount: 0,
+        totalTokens: 0,
+        completionTokens: 0,
+      },
+      createdAt: now,
+      startedAt: now,
+      endedAt: now,
+      durationMs: 0,
+      totalEvents: 0,
+      totalSpans: 0,
+    };
+  }
+}

package/src/recorder/chunk-manager.ts

@@ -0,0 +1,224 @@
+/**
+ * Chunk manager for the flight recorder.
+ * Handles chunk creation, compression, encryption, and storage.
+ */
+
+import type {
+  ChunkRef,
+  ChunkData,
+  StorageAdapter,
+  EncryptionConfig,
+} from "../types.js";
+import { generateKey, encrypt, type EncryptionKey } from "../crypto/encryption.js";
+import { compress, type CompressionType } from "../crypto/compression.js";
+import { sha256, merkleLeaf } from "../crypto/hashing.js";
+import type { BufferedEvent } from "./event-buffer.js";
+
+export interface ChunkCreateResult {
+  chunkRef: ChunkRef;
+  chunkData: ChunkData;
+  leafHash: string;
+}
+
+export class ChunkManager {
+  private chunks: ChunkRef[] = [];
+  private leafHashes: string[] = [];
+  private chunkIndex = 0;
+  private encryptionKey: EncryptionKey | null = null;
+
+  constructor(
+    private readonly storage: StorageAdapter,
+    private readonly encryptionConfig: EncryptionConfig,
+    private readonly compressionType: CompressionType = "gzip"
+  ) {}
+
+  /**
+   * Initialize encryption key for the session.
+   */
+  async initializeKey(): Promise<void> {
+    this.encryptionKey = await generateKey(this.encryptionConfig.algorithm);
+  }
+
+  /**
+   * Get the current encryption key ID.
+   */
+  getKeyId(): string | null {
+    return this.encryptionKey?.keyId ?? null;
+  }
+
+  /**
+   * Create a chunk from buffered events.
+   */
+  async createChunk(
+    events: BufferedEvent[],
+    eventRange: [number, number],
+    spanIds: string[]
+  ): Promise<ChunkCreateResult> {
+    if (!this.encryptionKey) {
+      throw new Error("Encryption key not initialized. Call initializeKey() first.");
+    }
+
+    // Serialize events to JSONL
+    const lines = events.map((e) => JSON.stringify(e.event));
+    const jsonl = lines.join("\n");
+    const rawData = new TextEncoder().encode(jsonl);
+
+    // Compress
+    const compressed = await compress(rawData, this.compressionType);
+
+    // Encrypt
+    const chunkMeta = {
+      index: this.chunkIndex,
+      eventRange,
+      spanIds,
+      createdAt: new Date().toISOString(),
+    };
+    const additionalData = new TextEncoder().encode(JSON.stringify(chunkMeta));
+    const encrypted = await encrypt(compressed.data, this.encryptionKey, additionalData);
+
+    // Create chunk data structure
+    const chunkData: ChunkData = {
+      ciphertext: encrypted.ciphertext,
+      nonce: encrypted.nonce,
+      tag: encrypted.tag,
+      meta: chunkMeta,
+    };
+
+    // Compute content hash of encrypted data
+    const encryptedPayload = new Uint8Array(
+      encrypted.ciphertext.length + encrypted.nonce.length + encrypted.tag.length
+    );
+    encryptedPayload.set(encrypted.ciphertext, 0);
+    encryptedPayload.set(encrypted.nonce, encrypted.ciphertext.length);
+    encryptedPayload.set(encrypted.tag, encrypted.ciphertext.length + encrypted.nonce.length);
+
+    const chunkHash = await sha256(encryptedPayload, "encryptedChunk");
+    const chunkId = `chunk-${this.chunkIndex.toString().padStart(6, "0")}-${chunkHash.slice(0, 16)}`;
+
+    // Store chunk
+    const storagePayload = this.serializeChunkForStorage(chunkData);
+    const storageRef = await this.storage.store(storagePayload);
+
+    // Create chunk reference
+    const chunkRef: ChunkRef = {
+      id: chunkId,
+      hash: chunkHash,
+      size: storagePayload.length,
+      storageUri: storageRef.uri,
+      encryptionKeyId: this.encryptionKey.keyId,
+      compression: this.compressionType === "gzip" ? "gzip" : "none",
+    };
+
+    // Compute Merkle leaf hash
+    const leafHash = await merkleLeaf(encryptedPayload);
+
+    // Track chunk
+    this.chunks.push(chunkRef);
+    this.leafHashes.push(leafHash);
+    this.chunkIndex++;
+
+    return {
+      chunkRef,
+      chunkData,
+      leafHash,
+    };
+  }
+
+  /**
+   * Get all chunk references.
+   */
+  getChunks(): ChunkRef[] {
+    return [...this.chunks];
+  }
+
+  /**
+   * Get all Merkle leaf hashes.
+   */
+  getLeafHashes(): string[] {
+    return [...this.leafHashes];
+  }
+
+  /**
+   * Get chunk count.
+   */
+  getChunkCount(): number {
+    return this.chunks.length;
+  }
+
+  /**
+   * Serialize chunk data for storage.
+   * Format: [4-byte meta length][meta JSON][nonce][tag][ciphertext]
+   */
+  private serializeChunkForStorage(chunk: ChunkData): Uint8Array {
+    const metaJson = JSON.stringify(chunk.meta);
+    const metaBytes = new TextEncoder().encode(metaJson);
+    const metaLength = new Uint32Array([metaBytes.length]);
+    const metaLengthBytes = new Uint8Array(metaLength.buffer);
+
+    const totalLength =
+      4 + // meta length
+      metaBytes.length +
+      chunk.nonce.length +
+      chunk.tag.length +
+      chunk.ciphertext.length;
+
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+
+    result.set(metaLengthBytes, offset);
+    offset += 4;
+
+    result.set(metaBytes, offset);
+    offset += metaBytes.length;
+
+    result.set(chunk.nonce, offset);
+    offset += chunk.nonce.length;
+
+    result.set(chunk.tag, offset);
+    offset += chunk.tag.length;
+
+    result.set(chunk.ciphertext, offset);
+
+    return result;
+  }
+
+  /**
+   * Deserialize chunk data from storage.
+   */
+  static deserializeChunkFromStorage(data: Uint8Array): ChunkData {
+    let offset = 0;
+
+    // Read meta length
+    const metaLengthBytes = data.slice(offset, offset + 4);
+    const metaLengthArr = new Uint32Array(metaLengthBytes.buffer);
+    const metaLength = metaLengthArr[0];
+    if (metaLength === undefined) {
+      throw new Error("Invalid chunk data: missing meta length");
+    }
+    offset += 4;
+
+    // Read meta
+    const metaBytes = data.slice(offset, offset + metaLength);
+    const metaJson = new TextDecoder().decode(metaBytes);
+    const meta = JSON.parse(metaJson) as ChunkData["meta"];
+    offset += metaLength;
+
+    // Read nonce (12 bytes for AES-GCM)
+    const nonce = data.slice(offset, offset + 12);
+    offset += 12;
+
+    // Read tag (16 bytes)
+    const tag = data.slice(offset, offset + 16);
+    offset += 16;
+
+    // Read ciphertext (rest)
+    const ciphertext = data.slice(offset);
+
+    return {
+      ciphertext,
+      nonce,
+      tag,
+      meta,
+    };
+  }
+}

package/src/recorder/event-buffer.ts

@@ -0,0 +1,124 @@
+/**
+ * In-memory event buffer for the flight recorder.
+ * Buffers events until chunk threshold is reached.
+ */
+
+import type { RecorderEvent } from "../types.js";
+import { sha256Json } from "../crypto/hashing.js";
+
+export interface BufferedEvent {
+  event: RecorderEvent;
+  serialized: Uint8Array;
+  hash: string;
+}
+
+export interface BufferStats {
+  eventCount: number;
+  byteSize: number;
+  oldestEventTs: string | null;
+  newestEventTs: string | null;
+}
+
+export class EventBuffer {
+  private events: BufferedEvent[] = [];
+  private byteSize = 0;
+  private seq = 0;
+
+  constructor(private readonly maxSizeBytes: number) {}
+
+  /**
+   * Add an event to the buffer.
+   * Returns true if buffer should be flushed (threshold reached).
+   */
+  async add(event: Omit<RecorderEvent, "seq">): Promise<boolean> {
+    const seqEvent = { ...event, seq: this.seq++ } as RecorderEvent;
+    const serialized = new TextEncoder().encode(JSON.stringify(seqEvent));
+    const hash = await sha256Json(seqEvent, "event");
+
+    this.events.push({
+      event: seqEvent,
+      serialized,
+      hash,
+    });
+
+    this.byteSize += serialized.length;
+
+    return this.byteSize >= this.maxSizeBytes;
+  }
+
+  /**
+   * Get all buffered events and clear the buffer.
+   */
+  flush(): BufferedEvent[] {
+    const events = this.events;
+    this.events = [];
+    this.byteSize = 0;
+    return events;
+  }
+
+  /**
+   * Peek at buffered events without clearing.
+   */
+  peek(): BufferedEvent[] {
+    return [...this.events];
+  }
+
+  /**
+   * Get buffer statistics.
+   */
+  getStats(): BufferStats {
+    return {
+      eventCount: this.events.length,
+      byteSize: this.byteSize,
+      oldestEventTs: this.events[0]?.event.ts ?? null,
+      newestEventTs: this.events[this.events.length - 1]?.event.ts ?? null,
+    };
+  }
+
+  /**
+   * Check if buffer is empty.
+   */
+  isEmpty(): boolean {
+    return this.events.length === 0;
+  }
+
+  /**
+   * Get current sequence number.
+   */
+  getSeq(): number {
+    return this.seq;
+  }
+
+  /**
+   * Get event range in buffer.
+   */
+  getEventRange(): [number, number] | null {
+    if (this.events.length === 0) return null;
+    const first = this.events[0];
+    const last = this.events[this.events.length - 1];
+    if (!first || !last) return null;
+    return [first.event.seq, last.event.seq];
+  }
+
+  /**
+   * Get unique span IDs in buffer.
+   */
+  getSpanIds(): string[] {
+    const spanIds = new Set<string>();
+    for (const { event } of this.events) {
+      if (event.spanId) {
+        spanIds.add(event.spanId);
+      }
+    }
+    return Array.from(spanIds);
+  }
+
+  /**
+   * Serialize all events to a single byte array (for chunking).
+   */
+  serialize(): Uint8Array {
+    const lines = this.events.map((e) => JSON.stringify(e.event));
+    const jsonl = lines.join("\n");
+    return new TextEncoder().encode(jsonl);
+  }
+}

package/src/recorder/index.ts

@@ -0,0 +1,3 @@
+export { FlightRecorder } from "./stream-recorder.js";
+export { EventBuffer } from "./event-buffer.js";
+export { ChunkManager } from "./chunk-manager.js";