@longarc/mdash 3.1.2 → 3.1.3

package/src/context/resolve.ts

@@ -0,0 +1,581 @@
+/**
+ * Caret — Constraint Resolution Engine
+ * @module @longarcstudios/caret/resolve
+ * 
+ * Resolve context fragments through their constraints.
+ * Determines if a fragment is valid for use in the current context.
+ */
+
+import type {
+  ContextFragment,
+  Constraint,
+  TimeConstraint,
+  ScopeConstraint,
+  TrustConstraint,
+  SignatureConstraint,
+  InfluenceConstraint,
+  InfluenceBudget,
+  ResolutionResult,
+  ConstraintViolation,
+  Timestamp,
+  TrustLevel,
+  Attribution,
+} from './types.js';
+import { isValidInfluenceBudget } from './types.js';
+import { getFragmentTrust, getFragmentAge } from './fragment.js';
+import { flattenChain } from './provenance.js';
+
+// ============================================================================
+// RESOLUTION CONTEXT
+// ============================================================================
+
+/** Context for resolution operations */
+export interface ResolutionContext {
+  /** Current domain for scope checking */
+  domain?: string;
+  
+  /** Current time for time constraint checking (default: now) */
+  current_time?: Date;
+  
+  /** Minimum required trust level */
+  min_trust?: TrustLevel;
+  
+  /** Required attributions */
+  required_attributions?: Attribution[];
+  
+  /** Known trusted signers */
+  trusted_signers?: string[];
+  
+  /** Current influence budget for MCCA compliance checking */
+  current_influence?: InfluenceBudget;
+}
+
+// ============================================================================
+// MAIN RESOLUTION FUNCTION
+// ============================================================================
+
+/**
+ * Resolve a fragment through its constraints.
+ * 
+ * @param fragment - The fragment to resolve
+ * @param context - Resolution context
+ * @returns Resolution result indicating success or violations
+ * 
+ * @example
+ * ```ts
+ * const result = await resolve(fragment, { 
+ *   domain: 'hr.company.com',
+ *   min_trust: 50 
+ * });
+ * 
+ * if (result.success) {
+ *   // Use fragment.content safely
+ * } else {
+ *   console.log('Violations:', result.violations);
+ * }
+ * ```
+ */
+export async function resolve<T = unknown>(
+  fragment: ContextFragment<T>,
+  context: ResolutionContext = {}
+): Promise<ResolutionResult<T>> {
+  const violations: ConstraintViolation[] = [];
+  const currentTime = context.current_time ?? new Date();
+  
+  // Check each constraint
+  for (const constraint of fragment.constraints) {
+    const violation = checkConstraint(constraint, fragment, context, currentTime);
+    if (violation) {
+      violations.push(violation);
+    }
+  }
+  
+  // Check context-level requirements (not in fragment constraints)
+  if (context.min_trust !== undefined) {
+    const trust = getFragmentTrust(fragment);
+    if (trust < context.min_trust) {
+      violations.push({
+        constraint: { kind: 'trust', minimum_trust: context.min_trust },
+        reason: `Fragment trust ${trust} is below required ${context.min_trust}`,
+        severity: 'error',
+      });
+    }
+  }
+  
+  if (context.required_attributions !== undefined) {
+    const records = flattenChain(fragment.provenance);
+    const attributions = new Set(records.map(r => r.attribution));
+    
+    for (const required of context.required_attributions) {
+      if (!attributions.has(required)) {
+        violations.push({
+          constraint: { kind: 'trust', minimum_trust: 0 as TrustLevel, required_attributions: context.required_attributions },
+          reason: `Missing required attribution: ${required}`,
+          severity: 'error',
+        });
+      }
+    }
+  }
+  
+  return {
+    success: violations.filter(v => v.severity === 'error').length === 0,
+    fragment: violations.filter(v => v.severity === 'error').length === 0 ? fragment : null,
+    violations,
+    resolved_at: new Date().toISOString() as Timestamp,
+  };
+}
+
+// ============================================================================
+// CONSTRAINT CHECKERS
+// ============================================================================
+
+/**
+ * Check a single constraint against a fragment.
+ */
+function checkConstraint(
+  constraint: Constraint,
+  fragment: ContextFragment,
+  context: ResolutionContext,
+  currentTime: Date
+): ConstraintViolation | null {
+  switch (constraint.kind) {
+    case 'time':
+      return checkTimeConstraint(constraint, fragment, currentTime);
+    case 'scope':
+      return checkScopeConstraint(constraint, context);
+    case 'trust':
+      return checkTrustConstraint(constraint, fragment);
+    case 'signature':
+      return checkSignatureConstraint(constraint, fragment, context);
+    case 'influence':
+      return checkInfluenceConstraint(constraint, context);
+    default:
+      return null;
+  }
+}
+
+/**
+ * Check time-based constraints.
+ */
+function checkTimeConstraint(
+  constraint: TimeConstraint,
+  fragment: ContextFragment,
+  currentTime: Date
+): ConstraintViolation | null {
+  // Check max_age
+  if (constraint.max_age_ms !== undefined) {
+    const age = getFragmentAge(fragment);
+    if (age > constraint.max_age_ms) {
+      return {
+        constraint,
+        reason: `Fragment age (${formatDuration(age)}) exceeds max_age (${formatDuration(constraint.max_age_ms)})`,
+        severity: 'error',
+      };
+    }
+  }
+  
+  // Check not_before
+  if (constraint.not_before !== undefined) {
+    const notBefore = new Date(constraint.not_before);
+    if (currentTime < notBefore) {
+      return {
+        constraint,
+        reason: `Current time is before not_before (${constraint.not_before})`,
+        severity: 'error',
+      };
+    }
+  }
+  
+  // Check not_after
+  if (constraint.not_after !== undefined) {
+    const notAfter = new Date(constraint.not_after);
+    if (currentTime > notAfter) {
+      return {
+        constraint,
+        reason: `Current time is after not_after (${constraint.not_after})`,
+        severity: 'error',
+      };
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Check scope-based constraints.
+ */
+function checkScopeConstraint(
+  constraint: ScopeConstraint,
+  context: ResolutionContext
+): ConstraintViolation | null {
+  if (!context.domain) {
+    // No domain context — can't verify scope
+    return {
+      constraint,
+      reason: 'No domain context provided for scope verification',
+      severity: 'warning',
+    };
+  }
+  
+  // Check denied domains first
+  if (constraint.denied_domains) {
+    for (const denied of constraint.denied_domains) {
+      if (domainMatches(context.domain, denied)) {
+        return {
+          constraint,
+          reason: `Domain ${context.domain} is in denied list`,
+          severity: 'error',
+        };
+      }
+    }
+  }
+  
+  // Check allowed domains
+  let allowed = false;
+  for (const allowedDomain of constraint.allowed_domains) {
+    if (domainMatches(context.domain, allowedDomain)) {
+      allowed = true;
+      break;
+    }
+  }
+  
+  if (!allowed) {
+    return {
+      constraint,
+      reason: `Domain ${context.domain} is not in allowed list`,
+      severity: 'error',
+    };
+  }
+  
+  return null;
+}
+
+/**
+ * Check trust-based constraints.
+ */
+function checkTrustConstraint(
+  constraint: TrustConstraint,
+  fragment: ContextFragment
+): ConstraintViolation | null {
+  const trust = getFragmentTrust(fragment);
+  
+  // Check minimum trust
+  if (trust < constraint.minimum_trust) {
+    return {
+      constraint,
+      reason: `Fragment trust ${trust} is below minimum ${constraint.minimum_trust}`,
+      severity: 'error',
+    };
+  }
+  
+  // Check required attributions
+  if (constraint.required_attributions) {
+    const records = flattenChain(fragment.provenance);
+    const attributions = new Set(records.map(r => r.attribution));
+    
+    for (const required of constraint.required_attributions) {
+      if (!attributions.has(required)) {
+        return {
+          constraint,
+          reason: `Missing required attribution: ${required}`,
+          severity: 'error',
+        };
+      }
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Check signature-based constraints.
+ */
+function checkSignatureConstraint(
+  constraint: SignatureConstraint,
+  fragment: ContextFragment,
+  _context: ResolutionContext
+): ConstraintViolation | null {
+  if (!constraint.required) {
+    return null;
+  }
+  
+  // Check if any record in the chain has a signature
+  const records = flattenChain(fragment.provenance);
+  const signedRecords = records.filter(r => r.signature !== undefined);
+  
+  if (signedRecords.length === 0) {
+    return {
+      constraint,
+      reason: 'No signatures found in provenance chain',
+      severity: 'error',
+    };
+  }
+  
+  // If allowed_signers specified, verify at least one matches
+  if (constraint.allowed_signers && constraint.allowed_signers.length > 0) {
+    const allowedSignersSet = new Set(constraint.allowed_signers);
+    const hasAllowedSigner = signedRecords.some(r => 
+      r.signature !== undefined && allowedSignersSet.has(r.signature)
+    );
+    
+    if (!hasAllowedSigner) {
+      return {
+        constraint,
+        reason: 'No signatures from allowed signers',
+        severity: 'error',
+      };
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Check influence-based constraints (MCCA compliance).
+ */
+function checkInfluenceConstraint(
+  constraint: InfluenceConstraint,
+  context: ResolutionContext
+): ConstraintViolation | null {
+  // First validate the constraint's budget itself
+  if (!isValidInfluenceBudget(constraint.budget)) {
+    return {
+      constraint,
+      reason: 'Constraint budget is not MCCA-compliant',
+      severity: constraint.enforcement === 'strict' ? 'error' : 'warning',
+    };
+  }
+  
+  // If no current influence in context, we can't verify compliance
+  if (!context.current_influence) {
+    return {
+      constraint,
+      reason: 'No current influence budget in resolution context',
+      severity: 'warning',
+    };
+  }
+  
+  const current = context.current_influence;
+  const budget = constraint.budget;
+  const violations: string[] = [];
+  
+  // Check each MCCA bound
+  if (current.system < budget.system) {
+    violations.push(`system influence ${current.system.toFixed(2)} below required ${budget.system.toFixed(2)}`);
+  }
+  if (current.user > budget.user) {
+    violations.push(`user influence ${current.user.toFixed(2)} exceeds limit ${budget.user.toFixed(2)}`);
+  }
+  if (current.environment > budget.environment) {
+    violations.push(`environment influence ${current.environment.toFixed(2)} exceeds limit ${budget.environment.toFixed(2)}`);
+  }
+  if (current.assistant > budget.assistant) {
+    violations.push(`assistant influence ${current.assistant.toFixed(2)} exceeds limit ${budget.assistant.toFixed(2)}`);
+  }
+  
+  if (violations.length > 0) {
+    return {
+      constraint,
+      reason: `MCCA violations: ${violations.join('; ')}`,
+      severity: constraint.enforcement === 'strict' ? 'error' : 'warning',
+    };
+  }
+  
+  return null;
+}
+
+// ============================================================================
+// BATCH RESOLUTION
+// ============================================================================
+
+/**
+ * Resolve multiple fragments at once.
+ * Returns only fragments that pass all constraints.
+ */
+export async function resolveAll<T = unknown>(
+  fragments: readonly ContextFragment<T>[],
+  context: ResolutionContext = {}
+): Promise<{
+  resolved: ContextFragment<T>[];
+  rejected: Array<{ fragment: ContextFragment<T>; violations: ConstraintViolation[] }>;
+}> {
+  const resolved: ContextFragment<T>[] = [];
+  const rejected: Array<{ fragment: ContextFragment<T>; violations: ConstraintViolation[] }> = [];
+  
+  for (const fragment of fragments) {
+    const result = await resolve(fragment, context);
+    
+    if (result.success && result.fragment) {
+      resolved.push(result.fragment);
+    } else {
+      rejected.push({ fragment, violations: [...result.violations] });
+    }
+  }
+  
+  return { resolved, rejected };
+}
+
+/**
+ * Filter fragments by trust level.
+ */
+export function filterByTrust<T>(
+  fragments: readonly ContextFragment<T>[],
+  minTrust: TrustLevel
+): ContextFragment<T>[] {
+  return fragments.filter(f => getFragmentTrust(f) >= minTrust);
+}
+
+/**
+ * Filter fragments by age.
+ */
+export function filterByAge<T>(
+  fragments: readonly ContextFragment<T>[],
+  maxAgeMs: number
+): ContextFragment<T>[] {
+  return fragments.filter(f => getFragmentAge(f) <= maxAgeMs);
+}
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Check if a domain matches a pattern.
+ * Supports wildcards: *.example.com matches sub.example.com
+ */
+function domainMatches(domain: string, pattern: string): boolean {
+  if (pattern === '*') {
+    return true;
+  }
+  
+  if (pattern.startsWith('*.')) {
+    const suffix = pattern.slice(1); // Remove the *
+    return domain.endsWith(suffix) || domain === pattern.slice(2);
+  }
+  
+  return domain === pattern;
+}
+
+/**
+ * Format a duration in milliseconds to human readable string.
+ */
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${Math.round(ms / 1000)}s`;
+  if (ms < 3600000) return `${Math.round(ms / 60000)}m`;
+  if (ms < 86400000) return `${Math.round(ms / 3600000)}h`;
+  return `${Math.round(ms / 86400000)}d`;
+}
+
+// ============================================================================
+// CONSTRAINT BUILDERS
+// ============================================================================
+
+/**
+ * Create a max age constraint.
+ */
+export function maxAge(duration: string | number): TimeConstraint {
+  const ms = typeof duration === 'number' ? duration : parseDuration(duration);
+  return { kind: 'time', max_age_ms: ms };
+}
+
+/**
+ * Create a not-before constraint.
+ */
+export function notBefore(time: Date | string): TimeConstraint {
+  const ts = typeof time === 'string' ? time : time.toISOString();
+  return { kind: 'time', not_before: ts as Timestamp };
+}
+
+/**
+ * Create a not-after constraint.
+ */
+export function notAfter(time: Date | string): TimeConstraint {
+  const ts = typeof time === 'string' ? time : time.toISOString();
+  return { kind: 'time', not_after: ts as Timestamp };
+}
+
+/**
+ * Create a scope constraint.
+ */
+export function allowDomains(...domains: string[]): ScopeConstraint {
+  return { kind: 'scope', allowed_domains: domains };
+}
+
+/**
+ * Create a minimum trust constraint.
+ */
+export function requireTrust(level: number): TrustConstraint {
+  return { kind: 'trust', minimum_trust: level as TrustLevel };
+}
+
+/**
+ * Create a signature requirement constraint.
+ */
+export function requireSignature(allowedSigners?: string[]): SignatureConstraint {
+  return { kind: 'signature', required: true, allowed_signers: allowedSigners };
+}
+
+/**
+ * Create an influence budget constraint (MCCA compliance).
+ * 
+ * @example
+ * ```ts
+ * // Strict MCCA enforcement
+ * requireInfluence({ system: 0.45, user: 0.30, environment: 0.15, assistant: 0.10 })
+ * 
+ * // Advisory mode (warnings only)
+ * requireInfluence({ system: 0.40, user: 0.35, environment: 0.20, assistant: 0.05 }, 'advisory')
+ * ```
+ */
+export function requireInfluence(
+  budget: InfluenceBudget,
+  enforcement: 'strict' | 'advisory' = 'strict'
+): InfluenceConstraint {
+  return { kind: 'influence', budget, enforcement };
+}
+
+/**
+ * Create a default MCCA-compliant influence constraint.
+ */
+export function requireMCCA(
+  overrides?: Partial<InfluenceBudget> | 'strict' | 'advisory',
+  enforcement: 'strict' | 'advisory' = 'strict'
+): InfluenceConstraint {
+  const defaults = {
+    system: 0.45,
+    user: 0.30,
+    environment: 0.15,
+    assistant: 0.10,
+  };
+
+  if (typeof overrides === 'string') {
+    return { kind: 'influence', budget: defaults, enforcement: overrides };
+  }
+
+  const budget = overrides ? { ...defaults, ...overrides } : defaults;
+  return { kind: 'influence', budget, enforcement };
+}
+
+/**
+ * Parse a duration string like "24h", "7d", "30m", "1w"
+ */
+function parseDuration(duration: string): number {
+  const match = duration.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)$/i);
+  if (!match || !match[1] || !match[2]) {
+    throw new Error(`Invalid duration format: ${duration}`);
+  }
+  
+  const value = parseFloat(match[1]);
+  const unit = match[2].toLowerCase();
+  
+  switch (unit) {
+    case 'ms': return value;
+    case 's': return value * 1000;
+    case 'm': return value * 60 * 1000;
+    case 'h': return value * 60 * 60 * 1000;
+    case 'd': return value * 24 * 60 * 60 * 1000;
+    case 'w': return value * 7 * 24 * 60 * 60 * 1000;
+    default: throw new Error(`Unknown duration unit: ${unit}`);
+  }
+}