@longarc/mdash 3.0.0

package/src/context/engine.ts

@@ -0,0 +1,598 @@
+/**
+ * mdash v3.0 - Sealed Context Architecture (SCA)
+ * 
+ * Incremental Merkle sealing with streaming support.
+ * O(log n) proof verification.
+ * 
+ * Target Latency:
+ * - Context chunk seal: <2ms P50, <5ms P99
+ */
+
+import {
+  Hash,
+  Seal,
+  Timestamp,
+  FragmentId,
+  generateFragmentId,
+  generateTimestamp,
+  sha256Object,
+  hmacSeal,
+  hmacVerify,
+  deriveKey,
+  deterministicStringify,
+} from '../core/crypto';
+
+import { IncrementalMerkleTree, CommitmentEngine } from '../core/commitment';
+
+// ============================================================================
+// CONTEXT TYPES
+// ============================================================================
+
+export type SourceClass = 
+  | 'system'      // Internal, fully trusted (100)
+  | 'operator'    // Human oversight (90)
+  | 'user'        // Authenticated user (70)
+  | 'derived'     // Computed from other contexts (60)
+  | 'agent'       // AI-generated (50)
+  | 'external';   // Third-party APIs (30)
+
+export type ContentType =
+  | 'text'
+  | 'structured'
+  | 'code'
+  | 'binary'
+  | 'reference';
+
+export interface SemanticUnit<T = unknown> {
+  /** Content type */
+  type: ContentType;
+  /** The actual data */
+  data: T;
+  /** Approximate token count */
+  tokens: number;
+  /** Optional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+export interface Provenance {
+  /** Source URI */
+  source: string;
+  /** Attribution type */
+  attribution: SourceClass;
+  /** Trust level (0-100) */
+  trust_level: number;
+  /** Creation timestamp */
+  timestamp: Timestamp;
+  /** Parent fragment (if derived) */
+  parent_hash: Hash | null;
+  /** Optional signature */
+  signature?: string;
+}
+
+export interface ContextFragment<T = unknown> {
+  /** Unique identifier */
+  id: FragmentId;
+  /** Content hash */
+  hash: Hash;
+  /** Semantic content */
+  content: SemanticUnit<T>;
+  /** Provenance chain */
+  provenance: Provenance;
+  /** Seal timestamp */
+  sealed_at: Timestamp;
+  /** HMAC seal */
+  seal: Seal;
+  /** Constraints for resolution */
+  constraints: ContextConstraint[];
+  /** Protocol version */
+  version: 'v3.0';
+}
+
+export interface ContextConstraint {
+  kind: 'time' | 'scope' | 'trust' | 'signature';
+  type: string;
+  params: Record<string, unknown>;
+}
+
+// ============================================================================
+// TRUST LEVELS
+// ============================================================================
+
+export const DEFAULT_TRUST_LEVELS: Record<SourceClass, number> = {
+  system: 100,
+  operator: 90,
+  user: 70,
+  derived: 60,
+  agent: 50,
+  external: 30,
+};
+
+// ============================================================================
+// CONTEXT STREAM - For incremental sealing
+// ============================================================================
+
+export interface StreamChunk<T = unknown> {
+  /** Chunk index */
+  index: number;
+  /** Chunk content */
+  content: T;
+  /** Chunk hash */
+  hash: Hash;
+  /** Sealed flag */
+  sealed: boolean;
+}
+
+export class ContextStream<T = unknown> {
+  private chunks: StreamChunk<T>[] = [];
+  private tree: IncrementalMerkleTree;
+  private key: CryptoKey | null = null;
+  private sourceClass: SourceClass;
+  private source: string;
+  
+  constructor(params: {
+    source: string;
+    sourceClass: SourceClass;
+    maxDepth?: number;
+  }) {
+    this.source = params.source;
+    this.sourceClass = params.sourceClass;
+    this.tree = new IncrementalMerkleTree(params.maxDepth || 16);
+  }
+  
+  /**
+   * Initialize with seal key
+   */
+  async initialize(sealKey: string): Promise<void> {
+    this.key = await deriveKey(sealKey);
+  }
+  
+  /**
+   * Add a chunk to the stream
+   * Target: <2ms P50, <5ms P99
+   */
+  async addChunk(content: T): Promise<StreamChunk<T>> {
+    const startTime = performance.now();
+    
+    const index = this.chunks.length;
+    const hash = await sha256Object({ index, content });
+    
+    const chunk: StreamChunk<T> = {
+      index,
+      content,
+      hash,
+      sealed: false,
+    };
+    
+    // Add to Merkle tree
+    await this.tree.addLeaf(hash);
+    chunk.sealed = true;
+    
+    this.chunks.push(chunk);
+    
+    const elapsed = performance.now() - startTime;
+    if (elapsed > 5) {
+      console.warn(`Context chunk seal exceeded P99: ${elapsed.toFixed(2)}ms`);
+    }
+    
+    return chunk;
+  }
+  
+  /**
+   * Get the current root hash
+   */
+  async getRoot(): Promise<Hash> {
+    return this.tree.getRoot();
+  }
+  
+  /**
+   * Get proof for a specific chunk
+   */
+  async getProof(index: number): Promise<{
+    chunk: StreamChunk<T>;
+    path: Array<{ hash: Hash; position: 'left' | 'right' }>;
+    root: Hash;
+  }> {
+    if (index < 0 || index >= this.chunks.length) {
+      throw new Error(`Invalid chunk index: ${index}`);
+    }
+    
+    const chunk = this.chunks[index];
+    if (!chunk) {
+      throw new Error(`Chunk not found at index: ${index}`);
+    }
+    const path = await this.tree.getProof(index);
+    const root = await this.tree.getRoot();
+    
+    return { chunk, path, root };
+  }
+  
+  /**
+   * Finalize the stream into a single sealed fragment
+   */
+  async finalize(): Promise<ContextFragment<T[]>> {
+    if (!this.key) {
+      throw new Error('Stream not initialized. Call initialize() first.');
+    }
+    
+    const id = generateFragmentId();
+    const now = generateTimestamp();
+    const root = await this.tree.getRoot();
+    
+    // Collect all chunk data
+    const data = this.chunks.map(c => c.content);
+    const totalTokens = this.chunks.length * 100; // Approximate
+    
+    const content: SemanticUnit<T[]> = {
+      type: 'structured',
+      data,
+      tokens: totalTokens,
+      metadata: {
+        chunks: this.chunks.length,
+        merkle_root: root,
+      },
+    };
+    
+    const provenance: Provenance = {
+      source: this.source,
+      attribution: this.sourceClass,
+      trust_level: DEFAULT_TRUST_LEVELS[this.sourceClass],
+      timestamp: now,
+      parent_hash: null,
+    };
+    
+    const hash = await sha256Object({
+      content,
+      provenance,
+      sealed_at: now,
+    });
+    
+    const sealData = {
+      _v: 1,
+      id,
+      hash,
+      content,
+      provenance,
+      sealed_at: now,
+      constraints: [],
+    };
+    
+    const seal = await hmacSeal(sealData, this.key);
+    
+    return {
+      id,
+      hash,
+      content,
+      provenance,
+      sealed_at: now,
+      seal,
+      constraints: [],
+      version: 'v3.0',
+    };
+  }
+  
+  /**
+   * Get stream statistics
+   */
+  getStats(): {
+    chunks: number;
+    treeStats: ReturnType<IncrementalMerkleTree['getStats']>;
+  } {
+    return {
+      chunks: this.chunks.length,
+      treeStats: this.tree.getStats(),
+    };
+  }
+}
+
+// ============================================================================
+// SEALED CONTEXT ENGINE
+// ============================================================================
+
+export class SealedContextEngine {
+  private key: CryptoKey | null = null;
+  private commitmentEngine: CommitmentEngine;
+  private fragments: Map<FragmentId, ContextFragment> = new Map();
+  private byHash: Map<Hash, FragmentId> = new Map();
+  
+  constructor(commitmentEngine: CommitmentEngine) {
+    this.commitmentEngine = commitmentEngine;
+  }
+  
+  /**
+   * Initialize the engine with a seal key
+   */
+  async initialize(sealKey: string): Promise<void> {
+    this.key = await deriveKey(sealKey);
+  }
+  
+  /**
+   * Create a sealed context fragment
+   */
+  async seal<T>(params: {
+    content: T;
+    contentType: ContentType;
+    source: string;
+    sourceClass: SourceClass;
+    parentHash?: Hash;
+    constraints?: ContextConstraint[];
+    tokens?: number;
+  }): Promise<ContextFragment<T>> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    const startTime = performance.now();
+    
+    const id = generateFragmentId();
+    const now = generateTimestamp();
+    
+    const semanticUnit: SemanticUnit<T> = {
+      type: params.contentType,
+      data: params.content,
+      tokens: params.tokens ?? this.estimateTokens(params.content),
+    };
+    
+    const provenance: Provenance = {
+      source: params.source,
+      attribution: params.sourceClass,
+      trust_level: DEFAULT_TRUST_LEVELS[params.sourceClass],
+      timestamp: now,
+      parent_hash: params.parentHash || null,
+    };
+    
+    const hash = await sha256Object({
+      content: semanticUnit,
+      provenance,
+      sealed_at: now,
+    });
+    
+    const sealData = {
+      _v: 1,
+      id,
+      hash,
+      content: semanticUnit,
+      provenance,
+      sealed_at: now,
+      constraints: params.constraints || [],
+    };
+    
+    const seal = await hmacSeal(sealData, this.key);
+    
+    const fragment: ContextFragment<T> = {
+      id,
+      hash,
+      content: semanticUnit,
+      provenance,
+      sealed_at: now,
+      seal,
+      constraints: params.constraints || [],
+      version: 'v3.0',
+    };
+    
+    // Commit to L1
+    await this.commitmentEngine.commit(fragment, `context:${id}`);
+    
+    // Store
+    this.fragments.set(id, fragment as ContextFragment);
+    this.byHash.set(hash, id);
+    
+    const elapsed = performance.now() - startTime;
+    if (elapsed > 5) {
+      console.warn(`Context seal exceeded P99: ${elapsed.toFixed(2)}ms`);
+    }
+    
+    return fragment;
+  }
+  
+  /**
+   * Derive a new fragment from an existing one
+   */
+  async derive<T, U>(params: {
+    parent: ContextFragment<T>;
+    transform: (data: T) => U;
+    source: string;
+    constraints?: ContextConstraint[];
+  }): Promise<ContextFragment<U>> {
+    const derived = params.transform(params.parent.content.data);
+    
+    const sealParams: {
+      content: U;
+      contentType: ContentType;
+      source: string;
+      sourceClass: SourceClass;
+      parentHash: Hash;
+      constraints?: ContextConstraint[];
+    } = {
+      content: derived,
+      contentType: params.parent.content.type,
+      source: params.source,
+      sourceClass: 'derived',
+      parentHash: params.parent.hash,
+    };
+    
+    if (params.constraints) {
+      sealParams.constraints = params.constraints;
+    }
+    
+    return this.seal(sealParams);
+  }
+  
+  /**
+   * Verify a fragment
+   */
+  async verify<T>(fragment: ContextFragment<T>): Promise<boolean> {
+    if (!this.key) {
+      throw new Error('Engine not initialized. Call initialize() first.');
+    }
+    
+    // Verify hash
+    const expectedHash = await sha256Object({
+      content: fragment.content,
+      provenance: fragment.provenance,
+      sealed_at: fragment.sealed_at,
+    });
+    
+    if (expectedHash !== fragment.hash) {
+      return false;
+    }
+    
+    // Verify seal
+    const sealData = {
+      _v: 1,
+      id: fragment.id,
+      hash: fragment.hash,
+      content: fragment.content,
+      provenance: fragment.provenance,
+      sealed_at: fragment.sealed_at,
+      constraints: fragment.constraints,
+    };
+    
+    return hmacVerify(sealData, fragment.seal, this.key);
+  }
+  
+  /**
+   * Resolve a fragment (check constraints)
+   */
+  async resolve<T>(
+    fragment: ContextFragment<T>,
+    context: { domain?: string; now?: Date }
+  ): Promise<{
+    success: boolean;
+    violations: Array<{ constraint: ContextConstraint; reason: string }>;
+  }> {
+    const violations: Array<{ constraint: ContextConstraint; reason: string }> = [];
+    const now = context.now || new Date();
+    
+    for (const constraint of fragment.constraints) {
+      switch (constraint.kind) {
+        case 'time': {
+          if (constraint.type === 'max_age') {
+            const maxAgeMs = constraint.params.max_age_ms as number;
+            const sealedAt = new Date(fragment.sealed_at);
+            if (now.getTime() - sealedAt.getTime() > maxAgeMs) {
+              violations.push({
+                constraint,
+                reason: `Fragment age exceeds max_age_ms: ${maxAgeMs}`,
+              });
+            }
+          }
+          break;
+        }
+        
+        case 'trust': {
+          if (constraint.type === 'minimum') {
+            const minTrust = constraint.params.minimum_trust as number;
+            if (fragment.provenance.trust_level < minTrust) {
+              violations.push({
+                constraint,
+                reason: `Trust ${fragment.provenance.trust_level} < required ${minTrust}`,
+              });
+            }
+          }
+          break;
+        }
+        
+        case 'scope': {
+          if (constraint.type === 'domain' && context.domain) {
+            const allowed = constraint.params.allowed_domains as string[];
+            if (!allowed.includes(context.domain)) {
+              violations.push({
+                constraint,
+                reason: `Domain ${context.domain} not in allowed list`,
+              });
+            }
+          }
+          break;
+        }
+      }
+    }
+    
+    return {
+      success: violations.length === 0,
+      violations,
+    };
+  }
+  
+  /**
+   * Get fragment by ID
+   */
+  get<T>(id: FragmentId): ContextFragment<T> | null {
+    return (this.fragments.get(id) as ContextFragment<T>) || null;
+  }
+  
+  /**
+   * Get fragment by hash
+   */
+  getByHash<T>(hash: Hash): ContextFragment<T> | null {
+    const id = this.byHash.get(hash);
+    if (!id) return null;
+    return this.get(id);
+  }
+  
+  /**
+   * Create a streaming context
+   */
+  createStream<T>(params: {
+    source: string;
+    sourceClass: SourceClass;
+  }): ContextStream<T> {
+    return new ContextStream<T>(params);
+  }
+  
+  /**
+   * Estimate tokens (rough: ~4 chars/token)
+   */
+  private estimateTokens(content: unknown): number {
+    const str = typeof content === 'string' 
+      ? content 
+      : deterministicStringify(content);
+    return Math.ceil(str.length / 4);
+  }
+  
+  /**
+   * Get statistics
+   */
+  getStats(): {
+    fragments: number;
+  } {
+    return {
+      fragments: this.fragments.size,
+    };
+  }
+}
+
+// ============================================================================
+// CONSTRAINT BUILDERS
+// ============================================================================
+
+export function maxAge(ms: number): ContextConstraint {
+  return {
+    kind: 'time',
+    type: 'max_age',
+    params: { max_age_ms: ms },
+  };
+}
+
+export function requireTrust(minimum: number): ContextConstraint {
+  return {
+    kind: 'trust',
+    type: 'minimum',
+    params: { minimum_trust: minimum },
+  };
+}
+
+export function allowDomains(domains: string[]): ContextConstraint {
+  return {
+    kind: 'scope',
+    type: 'domain',
+    params: { allowed_domains: domains },
+  };
+}
+
+export function requireSignature(signers: string[]): ContextConstraint {
+  return {
+    kind: 'signature',
+    type: 'required',
+    params: { allowed_signers: signers },
+  };
+}