@longarc/mdash 3.1.2 → 3.1.3

package/src/context/compose.ts

@@ -0,0 +1,388 @@
+/**
+ * Caret — Manifold Composition Engine
+ * @module @longarcstudios/caret/compose
+ * 
+ * Compose multiple context fragments into a single manifold.
+ * Handles token budgeting, semantic compression, and provenance merging.
+ */
+
+import type {
+  ContextFragment,
+  Manifold,
+  FragmentId,
+  Timestamp,
+  Seal,
+  TokenCount,
+  ComposeOptions,
+  CompositionStrategy,
+  TrustLevel,
+} from './types.js';
+import { sha256Object } from './crypto/hash.js';
+import { hmacSeal } from './crypto/hmac.js';
+import { mergeChains, getMinTrust } from './provenance.js';
+import { createSemanticUnit, getFragmentTrust } from './fragment.js';
+
+// ============================================================================
+// TOKEN PARSING
+// ============================================================================
+
+/**
+ * Parse a token ceiling specification.
+ * Accepts number or string like "8k tokens", "16k", "4096"
+ */
+export function parseTokenCeiling(ceiling: TokenCount | string): TokenCount {
+  if (typeof ceiling === 'number') {
+    return ceiling as TokenCount;
+  }
+  
+  const str = ceiling.toLowerCase().replace(/\s+/g, '').replace('tokens', '');
+  
+  // Handle k/K suffix
+  if (str.endsWith('k')) {
+    const num = parseFloat(str.slice(0, -1));
+    return Math.floor(num * 1000) as TokenCount;
+  }
+  
+  // Handle m/M suffix (millions)
+  if (str.endsWith('m')) {
+    const num = parseFloat(str.slice(0, -1));
+    return Math.floor(num * 1000000) as TokenCount;
+  }
+  
+  return parseInt(str, 10) as TokenCount;
+}
+
+// ============================================================================
+// COMPOSITION STRATEGIES
+// ============================================================================
+
+/**
+ * Sort fragments by strategy.
+ */
+function sortByStrategy(
+  fragments: readonly ContextFragment[],
+  strategy: CompositionStrategy
+): ContextFragment[] {
+  const copy = [...fragments];
+  
+  switch (strategy) {
+    case 'concatenate':
+      // Keep original order
+      return copy;
+      
+    case 'priority':
+      // Sort by trust level (highest first)
+      return copy.sort((a, b) => getFragmentTrust(b) - getFragmentTrust(a));
+      
+    case 'recency':
+      // Sort by sealed_at (most recent first)
+      return copy.sort((a, b) => 
+        new Date(b.sealed_at).getTime() - new Date(a.sealed_at).getTime()
+      );
+      
+    case 'semantic':
+      // For now, same as priority — true semantic dedup would need embeddings
+      return copy.sort((a, b) => getFragmentTrust(b) - getFragmentTrust(a));
+      
+    default:
+      return copy;
+  }
+}
+
+/**
+ * Select fragments that fit within token ceiling.
+ */
+function selectFragments(
+  fragments: readonly ContextFragment[],
+  ceiling: TokenCount,
+  minTrust?: TrustLevel
+): {
+  included: ContextFragment[];
+  excluded: ContextFragment[];
+  totalTokens: TokenCount;
+} {
+  const included: ContextFragment[] = [];
+  const excluded: ContextFragment[] = [];
+  let totalTokens = 0 as TokenCount;
+  
+  for (const fragment of fragments) {
+    // Check trust level filter
+    if (minTrust !== undefined && getFragmentTrust(fragment) < minTrust) {
+      excluded.push(fragment);
+      continue;
+    }
+    
+    const fragmentTokens = fragment.content.token_count;
+    
+    // Check if adding this fragment would exceed ceiling
+    if ((totalTokens as number) + (fragmentTokens as number) <= (ceiling as number)) {
+      included.push(fragment);
+      totalTokens = ((totalTokens as number) + (fragmentTokens as number)) as TokenCount;
+    } else {
+      excluded.push(fragment);
+    }
+  }
+  
+  return { included, excluded, totalTokens };
+}
+
+// ============================================================================
+// MANIFOLD CREATION
+// ============================================================================
+
+/**
+ * Generate a UUID v4 for manifold ID.
+ * SECURITY: Never falls back to Math.random — fails instead.
+ */
+function generateManifoldId(): FragmentId {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    return crypto.randomUUID() as FragmentId;
+  }
+  
+  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    
+    bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+    bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+    
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}` as FragmentId;
+  }
+  
+  throw new Error('Cryptographically secure random number generator not available');
+}
+
+/**
+ * Compose multiple fragments into a manifold.
+ * 
+ * @param fragments - The fragments to compose
+ * @param options - Composition options
+ * @param seal_key - Secret key for sealing
+ * @returns Promise resolving to the composed manifold
+ * 
+ * @example
+ * ```ts
+ * const manifold = await compose([
+ *   policyFragment,
+ *   userContextFragment,
+ *   agentStateFragment
+ * ], { ceiling: '8k tokens' }, 'secret-key');
+ * ```
+ */
+export async function compose<T = unknown>(
+  fragments: readonly ContextFragment[],
+  options: ComposeOptions,
+  seal_key: string
+): Promise<Manifold<T>> {
+  if (fragments.length === 0) {
+    throw new Error('Cannot compose empty fragment array');
+  }
+  
+  const ceiling = parseTokenCeiling(options.ceiling);
+  const strategy = options.strategy ?? 'priority';
+  const preserveProvenance = options.preserve_provenance ?? true;
+  const minTrust = options.min_trust as TrustLevel | undefined;
+
+  // Sort fragments by strategy
+  const sorted = sortByStrategy(fragments, strategy);
+
+  // Select fragments within ceiling
+  const { included, excluded, totalTokens } = selectFragments(
+    sorted,
+    ceiling,
+    minTrust
+  );
+  
+  if (included.length === 0) {
+    throw new Error('No fragments fit within token ceiling');
+  }
+  
+  // Compose content
+  const composedData = composeContent(included);
+  const content = createSemanticUnit<T>(composedData as T, {
+    type: 'composite',
+  });
+  
+  // Merge provenance chains
+  const firstIncluded = included[0];
+  if (!firstIncluded) {
+    throw new Error('No fragments to compose');
+  }
+  const provenance = preserveProvenance
+    ? await mergeChains(included.map(f => f.provenance))
+    : firstIncluded.provenance;
+  
+  // Generate manifold ID
+  const id = generateManifoldId();
+  
+  // Compute hash
+  const hash = await sha256Object({
+    id,
+    content,
+    sources: included.map(f => f.id),
+    provenance,
+  });
+  
+  // Create composition metadata
+  const composition = {
+    strategy,
+    ceiling,
+    actual_tokens: totalTokens,
+    fragments_included: included.length,
+    fragments_excluded: excluded.length,
+    compression_applied: false, // TODO: implement compression
+  };
+  
+  const created_at = new Date().toISOString() as Timestamp;
+  
+  // Create seal
+  const seal = await hmacSeal({
+    id,
+    hash,
+    content,
+    sources: included.map(f => f.id),
+    provenance,
+    composition,
+    created_at,
+  }, seal_key) as Seal;
+  
+  return {
+    id,
+    hash,
+    content,
+    sources: included.map(f => f.id),
+    provenance,
+    composition,
+    created_at,
+    seal,
+  };
+}
+
+/**
+ * Compose content from multiple fragments.
+ * For now, creates a structured object with all content.
+ * More sophisticated merging could be added later.
+ */
+function composeContent(fragments: ContextFragment[]): unknown {
+  // For text fragments, concatenate
+  const textFragments = fragments.filter(f => f.content.type === 'text');
+  if (textFragments.length === fragments.length) {
+    return textFragments.map(f => f.content.data).join('\n\n---\n\n');
+  }
+  
+  // For mixed types, create structured object
+  return {
+    fragments: fragments.map(f => ({
+      id: f.id,
+      type: f.content.type,
+      data: f.content.data,
+      source: f.provenance.head.source,
+      trust: f.provenance.head.trust_level,
+    })),
+  };
+}
+
+// ============================================================================
+// MANIFOLD OPERATIONS
+// ============================================================================
+
+/**
+ * Verify a manifold's integrity.
+ */
+export async function verifyManifold(
+  manifold: Manifold,
+  seal_key: string
+): Promise<{
+  valid: boolean;
+  errors: string[];
+}> {
+  const errors: string[] = [];
+  
+  // Verify hash
+  const expectedHash = await sha256Object({
+    id: manifold.id,
+    content: manifold.content,
+    sources: manifold.sources,
+    provenance: manifold.provenance,
+  });
+  
+  if (expectedHash !== manifold.hash) {
+    errors.push('Manifold hash mismatch');
+  }
+  
+  // Verify seal
+  const expectedSeal = await hmacSeal({
+    id: manifold.id,
+    hash: manifold.hash,
+    content: manifold.content,
+    sources: manifold.sources,
+    provenance: manifold.provenance,
+    composition: manifold.composition,
+    created_at: manifold.created_at,
+  }, seal_key);
+  
+  if (expectedSeal !== manifold.seal) {
+    errors.push('Manifold seal verification failed');
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Get summary statistics for a manifold.
+ */
+export function getManifoldStats(manifold: Manifold): {
+  tokens: TokenCount;
+  fragments: number;
+  utilization: number;
+  minTrust: TrustLevel;
+} {
+  return {
+    tokens: manifold.composition.actual_tokens,
+    fragments: manifold.composition.fragments_included,
+    utilization: (manifold.composition.actual_tokens as number) / (manifold.composition.ceiling as number),
+    minTrust: getMinTrust(manifold.provenance),
+  };
+}
+
+/**
+ * Check if a manifold is within a given token budget.
+ */
+export function fitsInBudget(manifold: Manifold, budget: TokenCount | string): boolean {
+  const budgetTokens = parseTokenCeiling(budget);
+  return (manifold.content.token_count as number) <= (budgetTokens as number);
+}
+
+// ============================================================================
+// RECOMPOSITION
+// ============================================================================
+
+/**
+ * Recompose a manifold with a different token ceiling.
+ * Requires access to original fragments.
+ */
+export async function recompose<T = unknown>(
+  originalFragments: readonly ContextFragment[],
+  newOptions: ComposeOptions,
+  seal_key: string
+): Promise<Manifold<T>> {
+  return compose(originalFragments, newOptions, seal_key);
+}
+
+/**
+ * Extend a manifold with additional fragments.
+ * Creates a new manifold (immutable).
+ */
+export async function extendManifold<T = unknown>(
+  originalFragments: readonly ContextFragment[],
+  additionalFragments: readonly ContextFragment[],
+  options: ComposeOptions,
+  seal_key: string
+): Promise<Manifold<T>> {
+  const allFragments = [...originalFragments, ...additionalFragments];
+  return compose(allFragments, options, seal_key);
+}

package/src/context/crypto/hash.ts

@@ -0,0 +1,277 @@
+/**
+ * Caret — Cryptographic Hash Utilities
+ * @module @longarcstudios/caret/crypto/hash
+ * 
+ * SHA-256 implementation using Web Crypto API (browser + Node compatible).
+ * All hashing is deterministic — same input always produces same output.
+ */
+
+import type { Hash } from '../types.js';
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/** SHA-256 produces 256 bits = 64 hex characters */
+const HASH_LENGTH = 64;
+
+/** Algorithm identifier for Web Crypto */
+const ALGORITHM = 'SHA-256';
+
+// ============================================================================
+// TEXT ENCODER
+// ============================================================================
+
+/** 
+ * Get TextEncoder instance.
+ * Works in both browser and Node.js environments.
+ */
+const getEncoder = (): TextEncoder => {
+  if (typeof TextEncoder !== 'undefined') {
+    return new TextEncoder();
+  }
+  // Node.js fallback (though TextEncoder is available in Node 11+)
+  throw new Error('TextEncoder not available');
+};
+
+// ============================================================================
+// CRYPTO IMPLEMENTATION
+// ============================================================================
+
+/**
+ * Get the crypto implementation for the current environment.
+ * Supports browser (window.crypto) and Node.js (crypto.subtle).
+ */
+async function getCrypto(): Promise<SubtleCrypto> {
+  // Browser environment
+  if (typeof window !== 'undefined' && window.crypto?.subtle) {
+    return window.crypto.subtle;
+  }
+  
+  // Node.js environment
+  if (typeof globalThis !== 'undefined' && (globalThis as any).crypto?.subtle) {
+    return (globalThis as any).crypto.subtle;
+  }
+  
+  // Node.js < 19 fallback
+  try {
+    const crypto = await import('crypto');
+    if (crypto.webcrypto?.subtle) {
+      return crypto.webcrypto.subtle as SubtleCrypto;
+    }
+  } catch {
+    // Import failed
+  }
+  
+  throw new Error('No crypto implementation available');
+}
+
+/**
+ * Convert ArrayBuffer to hexadecimal string.
+ */
+function bufferToHex(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let hex = '';
+  for (let i = 0; i < bytes.length; i++) {
+    const byte = bytes[i];
+    if (byte !== undefined) {
+      hex += byte.toString(16).padStart(2, '0');
+    }
+  }
+  return hex;
+}
+
+/**
+ * Convert hexadecimal string to ArrayBuffer.
+ */
+export function hexToBuffer(hex: string): ArrayBuffer {
+  if (hex.length % 2 !== 0) {
+    throw new Error('Invalid hex string length');
+  }
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+  }
+  return bytes.buffer;
+}
+
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+
+/**
+ * Compute SHA-256 hash of a string.
+ * 
+ * @param input - The string to hash
+ * @returns Promise resolving to the hash as a branded Hash type
+ * 
+ * @example
+ * ```ts
+ * const hash = await sha256('hello world');
+ * // => 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9'
+ * ```
+ */
+export async function sha256(input: string): Promise<Hash> {
+  const crypto = await getCrypto();
+  const encoder = getEncoder();
+  const data = encoder.encode(input);
+  const hashBuffer = await crypto.digest(ALGORITHM, data);
+  return bufferToHex(hashBuffer) as Hash;
+}
+
+/**
+ * Compute SHA-256 hash of binary data.
+ * 
+ * @param data - The binary data to hash
+ * @returns Promise resolving to the hash
+ */
+export async function sha256Binary(data: ArrayBuffer | Uint8Array): Promise<Hash> {
+  const crypto = await getCrypto();
+  const buffer = data instanceof Uint8Array ? new Uint8Array(data).buffer as ArrayBuffer : data;
+  const hashBuffer = await crypto.digest(ALGORITHM, buffer);
+  return bufferToHex(hashBuffer) as Hash;
+}
+
+/**
+ * Compute SHA-256 hash of a JSON-serializable object.
+ * Uses deterministic JSON serialization (sorted keys).
+ * 
+ * @param obj - The object to hash
+ * @returns Promise resolving to the hash
+ * 
+ * @example
+ * ```ts
+ * const hash = await sha256Object({ b: 2, a: 1 });
+ * // Same as sha256Object({ a: 1, b: 2 }) — deterministic
+ * ```
+ */
+export async function sha256Object(obj: unknown): Promise<Hash> {
+  const json = deterministicStringify(obj);
+  return sha256(json);
+}
+
+/**
+ * Compute a rolling hash combining multiple hashes.
+ * Used for chain verification in provenance tracking.
+ * 
+ * @param hashes - Array of hashes to combine
+ * @returns Promise resolving to the combined hash
+ */
+export async function rollingHash(hashes: readonly Hash[]): Promise<Hash> {
+  if (hashes.length === 0) {
+    // Hash of empty string for empty input
+    return sha256('');
+  }
+  
+  if (hashes.length === 1) {
+    const first = hashes[0];
+    if (!first) return sha256('');
+    return first;
+  }
+  
+  // Concatenate all hashes and hash the result
+  const combined = hashes.join('');
+  return sha256(combined);
+}
+
+/**
+ * Verify that a hash matches expected content.
+ * 
+ * @param content - The content to verify
+ * @param expectedHash - The expected hash
+ * @returns Promise resolving to boolean
+ */
+export async function verifyHash(content: string, expectedHash: Hash): Promise<boolean> {
+  const actualHash = await sha256(content);
+  return constantTimeEqual(actualHash, expectedHash);
+}
+
+/**
+ * Verify that an object's hash matches expected.
+ * 
+ * @param obj - The object to verify
+ * @param expectedHash - The expected hash
+ * @returns Promise resolving to boolean
+ */
+export async function verifyObjectHash(obj: unknown, expectedHash: Hash): Promise<boolean> {
+  const actualHash = await sha256Object(obj);
+  return constantTimeEqual(actualHash, expectedHash);
+}
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Deterministic JSON stringify with sorted keys.
+ * Ensures same object always produces same string.
+ */
+export function deterministicStringify(obj: unknown): string {
+  return JSON.stringify(obj, (_, value) => {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      // Sort object keys
+      const sorted: Record<string, unknown> = {};
+      const keys = Object.keys(value).sort();
+      for (const key of keys) {
+        sorted[key] = value[key];
+      }
+      return sorted;
+    }
+    return value;
+  });
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ * 
+ * @param a - First string
+ * @param b - Second string
+ * @returns true if equal, false otherwise
+ */
+export function constantTimeEqual(a: string, b: string): boolean {
+  // Use the longer length to prevent early exit timing leak
+  const len = Math.max(a.length, b.length);
+  
+  // Track both the XOR result and length mismatch
+  let result = a.length ^ b.length; // Will be non-zero if lengths differ
+  
+  for (let i = 0; i < len; i++) {
+    // Use 0 for out-of-bounds access (safe because result already tracks length diff)
+    const charA = i < a.length ? a.charCodeAt(i) : 0;
+    const charB = i < b.length ? b.charCodeAt(i) : 0;
+    result |= charA ^ charB;
+  }
+  
+  return result === 0;
+}
+
+/**
+ * Validate that a string is a valid SHA-256 hash.
+ * 
+ * @param value - The value to validate
+ * @returns true if valid hash format
+ */
+export function isValidHash(value: string): value is Hash {
+  return typeof value === 'string' && 
+    value.length === HASH_LENGTH && 
+    /^[a-f0-9]+$/i.test(value);
+}
+
+/**
+ * Create a Hash type from a raw string (unsafe — no validation).
+ * Use only when you've already validated the input.
+ */
+export function unsafeHash(value: string): Hash {
+  return value as Hash;
+}
+
+/**
+ * Parse a string as a Hash, throwing if invalid.
+ */
+export function parseHash(value: string): Hash {
+  if (!isValidHash(value)) {
+    // SECURITY: Do not leak input value in error message
+    throw new Error('Invalid hash format');
+  }
+  return value;
+}