@longarc/mdash 3.1.2 → 3.1.3

package/src/context/index.ts

@@ -0,0 +1,427 @@
+/**
+ * mdash v3.1 — Context Module (formerly Caret)
+ * @module @longarcstudios/mdash/context
+ * @version 3.1.0
+ *
+ * The context primitive runtime, now integrated into mdash.
+ *
+ * Architecture: LLM at the edges, cryptography at the core.
+ *
+ * v3.1.0: Merged into mdash from Caret v0.2.0
+ * - MdashActionCode for standardized action vocabulary
+ * - InfluenceBudget for MCCA-compliant bounds
+ * - InfluenceConstraint for influence-based resolution
+ * - Outcome<T> for Intent-Experience-Utility tracking
+ * - Atomic encoding with coreference resolution
+ * - Utility learning and credit assignment utilities
+ * 
+ * @example
+ * ```ts
+ * import { createCaret, requireInfluence } from '@longarcstudios/caret';
+ * 
+ * const caret = createCaret({ seal_key: 'your-secret-key' });
+ * 
+ * // Seal content into a fragment with MCCA constraints
+ * const fragment = await caret.seal({
+ *   content: { message: 'Hello, world!' },
+ *   source: 'app://example/greeting',
+ *   attribution: 'system',
+ *   constraints: [
+ *     requireInfluence({ system: 0.45, user: 0.30, environment: 0.15, assistant: 0.10 })
+ *   ],
+ *   atomic_encoding: { enabled: true }
+ * });
+ * 
+ * // Compose multiple fragments
+ * const manifold = await caret.compose([
+ *   fragment,
+ *   anotherFragment
+ * ], { ceiling: '8k tokens' });
+ * 
+ * // Resolve through constraints
+ * const result = await caret.resolve(fragment);
+ * if (result.success) {
+ *   console.log('Fragment is valid:', result.fragment);
+ * }
+ * ```
+ */
+
+import type {
+  CaretRuntime,
+  CaretConfig,
+  ContextFragment,
+  Manifold,
+  SealOptions,
+  ComposeOptions,
+  ResolutionResult,
+  FragmentStore,
+  TrustLevel,
+  Attribution,
+  Constraint,
+} from './types.js';
+
+import { 
+  createFragment, 
+  verifyFragment, 
+  setTokenizer,
+} from './fragment.js';
+
+import { compose } from './compose.js';
+import { resolve } from './resolve.js';
+import type { ResolutionContext } from './resolve.js';
+import { MemoryStore } from './store.js';
+
+// ============================================================================
+// RUNTIME IMPLEMENTATION
+// ============================================================================
+
+/**
+ * Internal runtime state.
+ */
+interface RuntimeState {
+  config: CaretConfig;
+  store: FragmentStore;
+}
+
+/**
+ * Create the Caret runtime.
+ */
+function createRuntime(state: RuntimeState): CaretRuntime {
+  const { config, store } = state;
+  
+  return {
+    async seal<T>(options: SealOptions<T>): Promise<ContextFragment<T>> {
+      const fragment = await createFragment({
+        content: options.content,
+        source: options.source,
+        attribution: options.attribution,
+        trust_level: options.trust_level ?? getDefaultTrust(options.attribution, config),
+        constraints: options.constraints as Constraint[] | undefined,
+        parent: options.parent,
+        signature: options.signature,
+        seal_key: config.seal_key,
+      });
+      
+      // Store the fragment
+      await store.put(fragment);
+      
+      return fragment;
+    },
+    
+    async compose<T>(
+      fragments: readonly ContextFragment[],
+      options: ComposeOptions
+    ): Promise<Manifold<T>> {
+      return compose(fragments, options, config.seal_key);
+    },
+    
+    async resolve<T>(
+      fragment: ContextFragment<T>,
+      context?: ResolutionContext
+    ): Promise<ResolutionResult<T>> {
+      return resolve(fragment, context);
+    },
+    
+    async verify(fragment: ContextFragment): Promise<boolean> {
+      const result = await verifyFragment(fragment, config.seal_key);
+      return result.valid;
+    },
+    
+    get store(): FragmentStore {
+      return store;
+    },
+  };
+}
+
+/**
+ * Get default trust level for attribution.
+ */
+function getDefaultTrust(attribution: Attribution, config: CaretConfig): number {
+  switch (attribution) {
+    case 'system':
+      return 100;
+    case 'operator':
+      return 90;
+    case 'user':
+      return 70;
+    case 'derived':
+      return 60;
+    case 'agent':
+      return 50;
+    case 'external':
+      return 30;
+    default:
+      return config.default_trust as number;
+  }
+}
+
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+
+/**
+ * Options for creating a Caret instance.
+ */
+export interface CreateCaretOptions {
+  /** Secret key for HMAC sealing (required) */
+  seal_key: string;
+  
+  /** Default trust level for unspecified sources */
+  default_trust?: number;
+  
+  /** Whether to enforce signature requirements */
+  require_signatures?: boolean;
+  
+  /** Token counting strategy */
+  tokenizer?: 'cl100k' | 'p50k' | 'custom';
+  
+  /** Custom tokenizer function */
+  custom_tokenizer?: (text: string) => number;
+  
+  /** Custom store implementation */
+  store?: FragmentStore;
+}
+
+/**
+ * Create a Caret runtime instance.
+ * 
+ * @param options - Configuration options
+ * @returns The Caret runtime
+ * 
+ * @example
+ * ```ts
+ * const caret = createCaret({
+ *   seal_key: process.env.CARET_SEAL_KEY!,
+ *   default_trust: 50,
+ * });
+ * ```
+ */
+export function createCaret(options: CreateCaretOptions): CaretRuntime {
+  if (!options.seal_key) {
+    throw new Error('seal_key is required');
+  }
+  
+  // Enforce minimum key length for security (P5 fix: increased to 32)
+  if (options.seal_key.length < 32) {
+    throw new Error('seal_key must be at least 32 characters for security');
+  }
+  
+  // Build config with defaults
+  const config = {
+    seal_key: options.seal_key,
+    default_trust: (options.default_trust ?? 50) as TrustLevel,
+    require_signatures: options.require_signatures ?? false,
+    tokenizer: options.tokenizer ?? 'cl100k' as const,
+    custom_tokenizer: options.custom_tokenizer,
+  };
+  
+  // Set up tokenizer if custom provided
+  if (options.custom_tokenizer) {
+    setTokenizer((content) => {
+      const text = typeof content === 'string' ? content : JSON.stringify(content);
+      return options.custom_tokenizer!(text) as any;
+    });
+  }
+  
+  // Create or use provided store
+  const store = options.store ?? new MemoryStore(config.seal_key);
+  
+  return createRuntime({ config, store });
+}
+
+// ============================================================================
+// CONVENIENCE EXPORTS
+// ============================================================================
+
+// Re-export types
+export type {
+  // Core types
+  ContextFragment,
+  Manifold,
+  FragmentId,
+  Hash,
+  Seal,
+  Timestamp,
+  SourceURI,
+  TokenCount,
+  TrustLevel,
+  Attribution,
+  
+  // Semantic
+  SemanticUnit,
+  SemanticType,
+  
+  // Provenance
+  ProvenanceRecord,
+  ProvenanceChain,
+  
+  // Constraints
+  Constraint,
+  TimeConstraint,
+  ScopeConstraint,
+  TrustConstraint,
+  SignatureConstraint,
+  InfluenceConstraint,
+  
+  // MCCA & Action Codes (Research Patterns)
+  MdashActionCode,
+  InfluenceBudget,
+  
+  // Outcome Tracking (Intent-Experience-Utility)
+  Outcome,
+  ExecutionStep,
+  ExecutionTrace,
+  UtilityScore,
+  UtilityFeedback,
+  LiabilityShare,
+  StepCredit,
+  CreditAssignment,
+  CoreferenceContext,
+  
+  // Composition
+  ComposeOptions,
+  CompositionStrategy,
+  
+  // Resolution
+  ResolutionResult,
+  ConstraintViolation,
+  
+  // Runtime
+  CaretRuntime,
+  CaretConfig,
+  SealOptions,
+  FragmentStore,
+} from './types.js';
+
+// Re-export constraint builders
+export {
+  maxAge,
+  notBefore,
+  notAfter,
+  allowDomains,
+  requireTrust,
+  requireSignature,
+  requireInfluence,
+  requireMCCA,
+} from './resolve.js';
+
+// Re-export resolution context
+export type { ResolutionContext } from './resolve.js';
+
+// Re-export store utilities
+export {
+  MemoryStore,
+  CachedStore,
+  CompositeStore,
+  ExtendedMemoryStore,
+  createStore,
+} from './store.js';
+
+export type { EmbeddingFunction } from './store.js';
+
+// Re-export fragment utilities
+export {
+  verifyFragment,
+  serializeFragment,
+  deserializeFragment,
+  getFragmentAge,
+  getFragmentTrust,
+  isFragmentExpired,
+  countTokens,
+  setTokenizer,
+} from './fragment.js';
+
+// Re-export composition utilities
+export {
+  verifyManifold,
+  getManifoldStats,
+  fitsInBudget,
+  parseTokenCeiling,
+} from './compose.js';
+
+// Re-export provenance utilities
+export {
+  createProvenanceRecord,
+  createProvenanceChain,
+  extendProvenanceChain,
+  flattenChain,
+  verifyChain,
+  mergeChains,
+  getMinTrust,
+  getMaxTrust,
+} from './provenance.js';
+
+// Re-export crypto utilities
+export {
+  sha256,
+  sha256Object,
+  sha256Binary,
+  rollingHash,
+  verifyHash,
+  isValidHash,
+  deterministicStringify,
+} from './crypto/hash.js';
+
+export {
+  hmacSeal,
+  hmacVerify,
+  isValidSeal,
+} from './crypto/hmac.js';
+
+// Re-export type guards
+export {
+  isHash,
+  isFragmentId,
+  isTimestamp,
+  isTrustLevel,
+  isTokenCount,
+  isContextFragment,
+  isValidInfluenceBudget,
+  isMdashActionCode,
+  sumInfluence,
+} from './types.js';
+
+// Re-export research pattern utilities
+export {
+  // Atomic encoding
+  resolveCoreferences,
+  createDefaultContext,
+  hasUnresolvedCoreferences,
+  extractEntityIds,
+  canonicalEncode,
+  computeCommitmentHash,
+  isValidSubject,
+  isValidTimestamp,
+} from './utils/atomic.js';
+
+export {
+  // Utility learning
+  updateUtilityScore,
+  updateOutcomeUtility,
+  createInitialUtility,
+  createUtilityFromHistory,
+  predictSuccess,
+  expectedUtility,
+  compareUtility,
+  selectBestOutcome,
+} from './utils/utility.js';
+
+export {
+  // Credit assignment
+  assignCredit,
+  validateCreditAssignment,
+  attributeLiability,
+  validateLiabilityShares,
+  createDefaultInfluenceBudget,
+  isMCCACompliant,
+  normalizeInfluenceBudget,
+  addInfluenceBudgets,
+  computeTraceInfluence,
+} from './utils/credit.js';
+
+// Version export
+export const VERSION = '3.1.0';
+export const FORMERLY = 'Caret v0.2.0';
+
+/** Alias for createCaret - use this for new code */
+export const createContext = createCaret;